OpenTelemetry
Note: The OpenTelemetry support in Instana is in public beta. We are hard at work to make OpenTelemetry a first-class citizen in Instana.
Using the host agent as a proxy, OpenTelemetry implementations can send tracing and metric data to the Instana agent. The data is then sent to the Instana back end for processing.
- Activating OpenTelemetry Support
- TLS Encryption for OpenTelemetry Ingestion
- OpenTelemetry Logs
- OpenTelemetry Metrics
- OpenTelemetry Tracing
- Additional Components
Activating OpenTelemetry Support
The OpenTelemetry ingestion in the host agent is deactivated by default to not interfere with other collectors on the host. To enable the reception of OpenTelemetry data in the host agent, add the following snippet to your host agent's configuration.yaml
:
com.instana.plugin.opentelemetry:
enabled: <boolean> # legacy setting, will only enable grpc, defaults to false
grpc:
enabled: <boolean> # takes precedence over legacy settings above, defaults to true if "grpc:" is present
http:
enabled: <boolean> # allows to enable http endpoints, defaults to true if "http:" is present
After the configuration is activated, the host agent will activate a collector for OpenTelemetry's default OTLP (OpenTelemetry protocol) exporter on port 4317
for gRPC and on port 4318
for HTTP or HTTPS connections.
TLS Encryption for OpenTelemetry Ingestion
TLS encryption can be enabled on the Agent, so that all data send to the OpenTelemetry ingestion endpoint is TLS encrypted as well. See Enabling TLS Encryption for more information on how to set this up.
OpenTelemetry Logs
Collection of OpenTelemetry logs is not supported. The host agent will show some benign exceptions if it receives OpenTelemetry logs data.
OpenTelemetry Metrics
OpenTelemetry metrics appear as "OpenTelemetry Custom Metrics" associated with the host or with the process from where they are collected. You can query OpenTelemetry custom metrics using the "Dynamic Focus" and "Event &
Alerts" with entity.type:opentelemetry
or entity.type:otel
.
The sensor collects the as follows core metrics:
- Gauges
- Histograms
- Summaries
OpenTelemetry Tracing
Note: We are hard at work to make OpenTelemetry a first-class citizen with full interoperability with Instana's own AutoTrace technology!
Current Scope
- Correlate OpenTelemetry traces that use the default W3C Trace Context exporter over HTTP communication from Instana-monitored applications to OpenTelemetry monitored ones.
- Some support for the trace data semantics conventions.
Using OpenTelemetry with Other Trace Protocols
OpenTelemetry supports exporters others than its native otlp
, like Zipkin
and Jaeger
, as well as matching context-propagators. When using Jaeger or Zipkin exporters, the host agent will be able to ingest the
data and process them the same as with other Zipkin and Jaeger implementations; refer to the Zipkin documentation and Jaeger documentation, respectively.
Known Limitations
- No trace continuity with protocols other than HTTP; there is currently no common specification in the industry for propagating trace contexts with protocols other than HTTP, that is, there is no non-HTTP equivalent to W3C Trace Context.
- OpenTelemetry
links
are not supported. - Mixing the default context propagator with exporters other than
otlp
is not supported.
Infrastructure Correlation
For detailed information on infrastructure correlation on Linux hosts, see the documentation on the agent's HTTP API endpoint.
Note: The optional Instana Agent Service provided on Kubernetes via the Instana Agent Helm Chart is very useful in combination with the OpenTelemetry support. It ensures that the data is forwarded to the Instana Agent which runs on the same Kubernetes node. This allows the Instana Agent to populate the infrastructure correlation data correctly.
Additional Components
The OpenTelemetry specification defines a number of components and APIs for customization. Instana provides some of these components for different runtimes. These components can be added to an application that is monitored by OpenTelemetry. All of these are optional, they are not required for Instana's OpenTelemetry support.
OpenTelemetry Exporters
OpenTelemetry exporters are used to export data from the application under monitoring to an OpenTelemetry collector or back end. An Instana OpenTelemetry exporter converts the tracing data that is produced by OpenTelemetry instrumentations, converts it to the Instana format and sends it to an endpoint that processes Instana tracing data.
Note: The more common alternative approach to using an Instana OpenTelemetry exporter is to use the default OpenTelemetry protocol exporter (provided by the OpenTelemetry project) in the monitored application. This exporter only needs to be configured to send its data to Instana in the OpenTelemetry format. For more information, see Activating OpenTelemetry Support.
Available Instana OpenTelemetry Exporters
- Serverless Node.js Instana OpenTelemetry exporter: @instana/opentelemetry-exporter
- Serverless .NET Instana OpenTelemetry exporter: OpenTelemetry.Exporter.Instana
- Serverless Go Instana OpenTelemetry exporter: github.com/instana/go-otel-exporter
OpenTelemetry Propagators
Propagators translate between vendor-specific trace correlation headers and the OpenTelemetry trace context. If an incoming HTTP request contains the proprietary Instana trace correlation headers (X-INSTANA-T
and X-INSTANA-S
),
the Instana OpenTelemetry propagator creates an OpenTelemetry trace context with the trace ID and span ID from those headers. The OpenTelemetry tracer can continue the trace from that trace context. Also, if an OpenTelemetry trace context exists,
the Instana OpenTelemetry propagator will use it to inject the proprietary Instana trace correlation headers into outgoing requests.
Note: Instana tracers support the W3C trace context specification, which is the default correlation header format used by OpenTelemetry. Therefore you usually don't need to add an Instana OpenTelemetry propagator to your application. For more information about the exact level of support, see W3C Trace Context Support.
Available Instana OpenTelemetry Propagators
- Node.js: @opentelemetry/propagator-instana
OpenTelemetry Samplers
An OpenTelemetry sampler makes a sampling decision, that is, it decides whether tracing data is captured for a particular request or not. Instana OpenTelemetry samplers make this decision based on the sampled
flag of the trace
context. If the value of the sampled
flag is not false
, the sampler will decide to capture the request.
Available Instana OpenTelemetry Samplers
- Node.js: @instana/opentelemetry-sampler
OpenTelemetry Resource Detectors
Note: An Instana OpenTelemetry resource detector always requires an Instana agent to be deployed and running on the same host.
Instana OpenTelemetry resource detectors enrich OpenTelemetry tracing information with additional resource attributes. The additional attributes help to establish a link between the OpenTelemetry tracing data and the process infrastructure entities in Instana.
The following fields are attached to the resource:
process.pid
: the PID of the process in the root PID namespaceinstana.host.id
: the UUID of the Instana agent on this hostservice.instance.id
: the ID of the OpenTelemetry service; this ID will be used to correlate tracing data with the process entity