API

API Tokens

In order to use the REST API, you need to create an API token and assign permissions to it. API tokens are managed only by the account owner role, who can create multiple API tokens with varying permissions.

API token management can found in Settings → Access Control → API Tokens.

Instana REST API

The Instana REST API HTTP endpoints allow data retrieval, like traces and metrics, as well as configuration, like service extraction and users.

New API and a new documentation is available, it is still an early access version so please expect some more changes and improvements to it. The new version utilizes the new architecture for Application Perspectives, End User Montitoring and Traces retrieval. https://instana.github.io/openapi/

Deprecated (partialy already discontinued)

The old API documentation is available via Postman: https://documenter.getpostman.com/view/1527374/RWEiLJXR

Python REST API Client

To better utilize the REST API outlined above, we have put together a Python REST API Client for simple access to your data from Python.

To use the this client, you must have the Python Sensor installed (pip install instana) and optionally the following environment variables set:

INSTANA_API_TOKEN=<MY_API_TOKEN>
INSTANA_BASE_URL=https://<dashboard-url>

You can get an API token by navigating in your dashboard to Settings -> Access Control -> API Tokens. See also the section above.

Example Usage:

from instana.api import APIClient
c = APIClient(base_url="https://<dashboard-url>", api_token='MY_API_TOKEN')

# Or, alternatively if you have the environment variables set
# c = APIClient()

# Retrieve the current application view
av = c.application_view()
av.json()

# Retrieve the current infrastructure view
iv = c.infrastructure_view()

# Retrieve snapshots results from a query
ss = c.snapshots("entity.selfType:webService entity.service.name:\"pwpush.com\"")

# Get all EUM apps
ea = c.eum_apps()

# Get all Service Extraction Configs
sec = c.service_extraction_configs()

For more information, see the Python repository.

Agent REST API

The Instana Agent provides a web service API which accepts custom event and trace data.

Event SDK Web Service

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
  }
]

Ruby Example

duration = (Time.now.to_f * 1000).floor - deploy_start_time_in_ms
payload = {}
payload[:title] = 'Deployed MyApp'
payload[:text] = 'pglombardo deployed MyApp@revision'
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)
end

Curl Example

curl -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}'

PowerShell Example

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}'

Mina Integration

Learn more about our Mina event integration.

Trace SDK Web Service

Using the Trace SDK REST Web Service, it is possible to integrate Instana into any application written in any language. Each running Instana Agent can be used to feed in custom traces, which can be part of automatically captured traces or completely separated. 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>,
  'timestamp': <64 bit long>,
  'duration': <64 bit long>,
  'name' : <string>,
  'type' : <string>,
  'error' : <boolean>,
  'data' : {
    <string> : <string>
  }
}

spanId is an unique identifier for the span. Define the root span of a trace with the same spanId and traceId; define child spans with a unique spanId, the traceId of the root span and the spanId of the span immediately preceding in the hierarchy as parentId. Trace Id, Span Id and Parent Id are 64 bit unique values encoded as hex string like b0789916ff8f319f.

root (spanId=1, traceID=1)
   child (spanId=2,traceId=1, parentId=1)
      child (spanId=3, traceId=1, parentId=2)

timestamp and duration are in milliseconds. 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, but it is recommended to keep it simple. type is optional, but when given needs to be either ENTRY, EXIT or INTERMEDIATE. data is optional and can contain arbitrary key-value pairs. error is optional and can be set to true to indicate an erroneous span. Behaviour of supplying duplicate keys is unspecified.

The endpoint also accepts a batch of spans, which then need to be given as array:

[
  {
    // span as above
  },
  {
    // span as above
  }
]

Limitations

Adher to the following rate limits for the trace webservice:

  • Maximum API calls/sec: 20
  • Maximum payload per POST request: A span must not exceed 4 KiB. The request size must not exceed 4 MiB.
  • Maximum batch size (spans/array): 1000

FAQ

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 (splitted 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. An implementation of this transmission strategy can be seen here:

https://github.com/instana/nodejs-sensor/blob/6ec0d469006ad52f4d5fde7218b163e05bf5b2ad/src/tracing/transmission.js

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 https://docs.instana.io/quickstart/agentconfiguration/