Merge pull request #25 from instana/events-api

first simple event API

README.md

@@ -8,6 +8,8 @@ The Instana Go sensor consists of two parts:
 * metrics sensor
 * [OpenTracing](http://opentracing.io) tracer
 
+## Sensor
+
 To use sensor only without tracing ability, import the `instana` package and run
 
 	instana.InitSensor(opt)
@@ -20,6 +22,8 @@ in your main function. The init function takes an `Options` object with the foll
 
 Once initialised, the sensor will try to connect to the given Instana agent and in case of connection success will send metrics and snapshot information through the agent to the backend.
 
+## OpenTracing
+
 In case you want to use the OpenTracing tracer, it will automatically initialise the sensor and thus also activate the metrics stream. To activate the global tracer, run for example
 
 	ot.InitGlobalTracer(instana.NewTracerWithOptions(&instana.Options{
@@ -32,8 +36,19 @@ The tracer is able to protocol and piggyback OpenTracing baggage, tags and logs.
 
 The Instana tracer will remap OpenTracing HTTP headers into Instana Headers, so parallel use with some other OpenTracing model is not possible. The instana tracer is based on the OpenTracing Go basictracer with necessary modifications to map to the Instana tracing model. Also, sampling isn't implemented yet and will be focus of future work.
 
+## Events API
+
+The sensor, be it instantiated explicitly or implicitly throught the tracer, provides a simple wrapper API to send events into Instana as described in https://instana.atlassian.net/wiki/display/DOCS/Event+SDK+REST+Web+Service :
+
+	SentDefaultServiceEvent: send the event with default service name
+	SendServiceEvent: send the event for a service named explicitly
+	SendHostEvent: send an event that will not be assigned to a service, like in case of general events
+
+## Examples
+
 Following examples are included in the `examples` folder:
 
-* **simple** - demoes generally how to use the tracer
-* **http** - demoes how http server and client should be instrumented
-* **rpc** - demoes the fallback to RPC
+* **ot-simple/simple.go** - demoes generally how to use the tracer
+* **webserver/http.go** - demoes how http server and client should be instrumented
+* **rpc/rpc.go** - demoes the fallback to RPC
+* **event/event.go** - demoes the event API

agent.go

@@ -14,6 +14,7 @@ const (
 	AgentDiscoveryURL = "/com.instana.plugin.golang.discovery"
 	AgentTracesURL    = "/com.instana.plugin.golang/traces."
 	AgentDataURL      = "/com.instana.plugin.golang."
+	AgentEventURL     = "/com.instana.plugin.generic.event"
 	AgentDefaultHost  = "localhost"
 	AgentDefaultPort  = 42699
 	AgentHeader       = "Instana Agent"

event.go

@@ -0,0 +1,47 @@
+package instana
+
+type EventData struct {
+	Title    string `json:"title"`
+	Text     string `json:"text"`
+	Duration int    `json:"duration"`
+	Severity int    `json:"severity"`
+	Plugin   string `json:"plugin,omitempty"`
+	ID       string `json:"id,omitempty"`
+	Host     string `json:"host,omitempty"`
+}
+
+const (
+	ServicePlugin = "com.instana.forge.connection.http.logical.LogicalWebApp"
+	ServiceHost   = ""
+)
+
+func SendDefaultServiceEvent(title string, text string, severity int) {
+	SendServiceEvent(sensor.serviceName, title, text, severity)
+}
+
+func SendServiceEvent(service string, title string, text string, severity int) {
+	sendEvent(&EventData{
+		Title:    title,
+		Text:     text,
+		Duration: 0,
+		Severity: severity,
+		Plugin:   ServicePlugin,
+		ID:       service,
+		Host:     ServiceHost})
+}
+
+func SendHostEvent(title string, text string, severity int) {
+	sendEvent(&EventData{
+		Title:    title,
+		Text:     text,
+		Duration: 0,
+		Severity: severity})
+}
+
+func sendEvent(event *EventData) {
+
+	log.debug(event)
+
+	//we do fire & forget here, because the whole pid dance isn't necessary to send events
+	go sensor.agent.request(sensor.agent.makeURL(AgentEventURL), "POST", event)
+}

example/event/event.go

@@ -0,0 +1,27 @@
+package main
+
+import (
+	"time"
+
+	"github.com/instana/golang-sensor"
+)
+
+const (
+	service = "golang-event"
+)
+
+func main() {
+	instana.InitSensor(&instana.Options{
+		Service:  service,
+		LogLevel: instana.Debug})
+
+	go forever()
+	select {}
+}
+
+func forever() {
+	for {
+		instana.SendDefaultServiceEvent("Event from the Golang sample", "{field: data}", -1)
+		time.Sleep(5000 * time.Millisecond)
+	}
+}