The Instana Agent provides a web service API which accepts custom event and trace data.
Using the Event SDK REST Web Service, it is possible to integrate custom health checks and other event sources into Instana. Each one running the Instana Agent can be used to feed in manual events. The agent has an endpoint which listens on http://localhost:42699/com.instana.plugin.generic.event and accepts the following JSON via a POST request:
{
"title": <string>,
"text": <string>,
"severity": <integer> , -1, 5 or 10
"timestamp": <integer>, timestamp in milliseconds from epoch
"duration": <integer>, duration in milliseconds
}Title and text are used for display purposes.
Severity is an optional integer of -1, 5 and 10. A value of -1 or EMPTY will generate a Change. A value of 5 will generate a warning Issue, and a value of 10 will generate a critical Issue.
When absent, the event is treated as a change without severity. Timestamp is the timestamp of the event, but it is optional, in which case the current time is used. Duration can be used to mark a timespan for the event. It also is optional, in which case the event will be marked as "instant" rather than "from-to."
The endpoint also accepts a batch of events, which then need to be given as an array:
[
{
// event as above
},
{
// event as above
}
]duration = (Time.now.to_f * 1000).floor - deploy_start_time_in_ms
payload = {}
payload[:title] = 'Deployed MyApp'
payload[:text] = 'pglombardo deployed [email protected]'
payload[:duration] = duration
uri = URI('http://localhost:42699/com.instana.plugin.generic.event')
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req.body = payload.to_json
Net::HTTP.start(uri.hostname, uri.port) do |http|
http.request(req)
endcurl -XPOST http://localhost:42699/com.instana.plugin.generic.event -H "Content-Type: application/json" -d '{"title":"Custom API Events ", "text": "Failure Redeploying Service Duration", "duration": 5000, "severity": -1}'For PowerShell you can either use the standard Cmdlets Invoke-WebRequest or Invoke-RestMethod. The parameters to be provided are basically the same.
Invoke-RestMethod
-Uri http://localhost:42699/com.instana.plugin.generic.event
-Method POST
-Body '{"title":"PowerShell Event ", "text": "You used PowerShell to create this event!", "duration": 5000, "severity": -1}'Invoke-WebRequest
-Uri http://localhost:42699/com.instana.plugin.generic.event
-Method Post
-Body '{"title":"PowerShell Event ", "text": "You used PowerShell to create this event!", "duration": 5000, "severity": -1}'Learn more about our Mina event integration.
Using the Trace SDK REST Web Service, it is possible to integrate Instana into any application regardless of language. Each active Instana Agent can be used to feed manually captured traces into the Web Service, which can be joined with automatically captured traces or be completely separate. The Agent offers an endpoint which listens on http://localhost:42699/com.instana.plugin.generic.trace and accepts the following JSON via a POST request:
{
"spanId": <string>,
"parentId": <string>,
"traceId": <string>,
"backendTrace": <string>,
"timestamp": <64 bit long>,
"duration": <64 bit long>,
"name": <string>,
"type": <string>,
"error": <boolean>,
"data": {
<string> : <string>
}
}spanId is the unique identifier for any particular span. The trace is defined by a root span, that is, a span that does not have a parentId. The traceId needs to be identical for all spans that belong to the same trace, and is allowed to be overlapping with a spanId. traceId, spanId and parentId are 64 bit unique values encoded as hex string like b0789916ff8f319f. Spans form a hierarchy by referencing the spanId of the parent as parentId. An example of a span hierarchy in a trace is shown below:
root (spanId=1, traceId=1, type=Entry)
child A (spanId=2, traceId=1, parentId=1, type=Exit)
child A (spanId=3, traceId=1, parentId=2, type=Entry)
child B (spanId=4, traceId=1, parentId=3, type=Exit)
child B (spanId=5, traceId=1, parentId=4, type=Entry)backendTrace is optional and only used for connecting this span as the End-User Monitoring (EUM) span for the referenced backend traceId. The type needs to be set to EUM.
timestamp and duration are in milliseconds. The timestamp must be the epoch timestamp coordinated to UTC.
name can be any string which is used to visualize and group traces, and can contain any text. However, simplicity is recommended.
type is optional, when absent is treated as ENTRY. Options are ENTRY, EXIT, INTERMEDIATE, or EUM. Setting the type is important for the UI. It is assumed that after an ENTRY, child spans are INTERMEDIATE or EXIT. After an EXIT an ENTRY should follow. This is visualized as a remote call.
data is optional and can contain arbitrary key-value pairs. The behavior of supplying duplicate keys is unspecified.
error is optional and can be set to true to indicate an erroneous span.
The endpoint also accepts a batch of spans, which then need to be given as an array:
[
{
// span as above
},
{
// span as above
}
]For traces received via the Trace SDK Web Service the same rules regarding Conversion and Service/Endpoint Naming are applied as for the Java Trace SDK.
Adhere to the following rate limits for the trace web service:
Is there a limit for the amount of calls from Agent to Backend? Data transmission between Instana agent and Instana backend depends on a lot of factors. It is done using a persistent HTTP2 connection and highly optimized.
What is the optimal package size (the split size) to send 50,000 spans with a size about 40 MiB over the Agent to Backend? Recommended strategy is to buffer spans for up to one second or until 500 spans were collected, then transmit the spans to the agent. For an implementation of this transmission strategy, see our repo.
Which requirements are recommended for best Agent performance (cpu, ram, etc.)? This depends on the host that should be monitored, e.g. the number of Docker containers per host etc.
How should the agent environment be configured? See our agent configuration docs.