OpenTelemetry is a set of APIs, SDKs, tooling, and integrations that enable the creation and management of telemetry data. It formed through a merger of the OpenTracing and OpenCensus projects.

OpenTelemetry is an open-source project that provides the components necessary to observe your applications and services. If you’re unfamiliar with the project, see the spec for more information.

Elastic exporteredit

Elastic’s integration is designed to drop into your current OpenTelemetry setup. We’ve done this by extending the "contrib" OpenTelemetry collector and adding an Elastic exporter.

Before sending the data to the Elastic Stack, the exporter translates the OpenTelemetry trace data collected from your services and the metrics data collected from your applications and infrastructure to Elastic’s protocol. By extending the OpenTelemetry collector, no changes are needed in your instrumented services to begin using the Elastic Stack.

How the OpenTelemetry Collector worksedit

The OpenTelemetry collector uses the following three types of components to handle data:

Once a receiver, processor, and exporter is defined, pipelines can be configured in the services section of your configuration. The traces and metrics pipelines define the path of trace data and metrics through your collector and bring all three of these components together.

A final note: extensions can also be enabled for tasks like monitoring the health of the collector. See the OpenTelemetry extension readme for a list of supported extensions.

Plan your deploymentedit

OpenTelemetry Collectors can be run as an Agent, or as standalone collectors. They can be deployed as often as necessary and scaled up or out.

Deployment planning resources are available in OpenTelemetry’s Getting Started documentation and Collector Performance research.

Download the collectoredit

The Elastic exporter lives in the opentelemetry-collector-contrib repository, and the latest release can be downloaded from GitHub releases page.

Docker images are available on dockerhub:

docker pull otel/opentelemetry-collector-contrib

To export traces and metrics to the OpenTelemetry Collector, ensure that you have instrumented your services and applications with the OpenTelemetry API and/or SDK.

Here is an example of how to set up the OpenTelemetry Java agent.

export OTEL_RESOURCE_ATTRIBUTES=service.name=frontend,service.version=1.0-SNAPSHOT,deployment.environment=staging
java -javaagent:/path/to/opentelemetry-javaagent-all-0.15.0.jar \
     -Dotel.otlp.endpoint=http://my-otel-collector.mycompany.com:4317 \
     -jar target/frontend-1.0-SNAPSHOT.jar

Here is an example of how to capture business metrics from an application.

// initialize metric
Meter meter = GlobalMetricsProvider.getMeter("my-frontend");
DoubleCounter orderValueCounter = meter.doubleCounterBuilder("order_value").build();

public void createOrder(HttpServletRequest request) {

   // create order in the database
   ...
   // increment business metrics for monitoring
   orderValueCounter.add(orderPrice);
}

For more information on setting up OpenTelemetry, see OpenTelemetry’s Getting Started.

Configure the collectoredit

Create a yaml configuration file.

This example configuration file accepts input from an OpenTelemetry Agent, processes the data, and sends it to an Elasticsearch Service instance.

  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: 'localhost:4317'
    hostmetrics: 
      collection_interval: 1m
      scrapers:
        load:
        memory:

  processors:
    batch: null

  exporters:
    elastic:
      apm_server_url: 'https://elasticapm.example.com' 
      secret_token: 'APM_SERVER_SECRET_TOKEN'

  service:
    pipelines:
      metrics:
        receivers:
          - otlp
          - hostmetrics
        exporters:
          - elastic 
      traces:
        receivers:
          - otlp
        processors:
          - batch
        exporters:
          - elastic 

Caveatsedit

If collecting metrics, please note that the DoubleValueRecorder and LongValueRecorder metrics are not yet supported.

Use Discover to validate that metrics are successfully being reported to Kibana.

TSVB within Kibana is the recommended visualization for OpenTelemetry metrics. TSVB is a time series data visualizer that allows you to use the full power of the Elasticsearch aggregation framework. With TSVB, you can combine an infinite number of aggregations to display complex data.

In this example eCommerce OpenTelemetry dashboard, there are four visualizations; sales, order count, product cache, and system load. The dashboard provides us with business KPI metrics, along with performance-related metrics.

Let’s have a look at how this dashboard was created, specifically the Sales USD and System load visualizations.

apm_server_urledit

Elastic APM Server URL. (required)

api_keyedit

Credential for API key authorization. Must also be enabled in Elastic APM Server. (optional)

secret_tokenedit

Credential for secret token authorization. Must also be enabled in Elastic APM Server. (optional)

ca_fileedit

Root Certificate Authority (CA) certificate, for verifying the server’s identity if TLS is enabled. (optional)

cert_fileedit

Client TLS certificate. (optional)

key_fileedit

Client TLS key. (optional)

insecureedit

Disable verification of the server’s identity if TLS is enabled. (optional)