Exporters

Send telemetry to the OpenTelemetry Collector to make sure it’s exported correctly. Using the Collector in production environments is a best practice. To visualize your telemetry, export it to a backend such as Jaeger, Zipkin, Prometheus, or a vendor-specific backend.

Available exporters

The registry contains a list of exporters for JavaScript.

Among exporters, OpenTelemetry Protocol (OTLP) exporters are designed with the OpenTelemetry data model in mind, emitting OTel data without any loss of information. Furthermore, many tools that operate on telemetry data support OTLP (such as Prometheus, Jaeger, and most vendors), providing you with a high degree of flexibility when you need it. To learn more about OTLP, see OTLP Specification.

This page covers the main OpenTelemetry JavaScript exporters and how to set them up.

OTLP

Collector Setup

To try out and verify your OTLP exporters, you can run the collector in a docker container that writes telemetry directly to the console.

In an empty directory, create a file called collector-config.yaml with the following content:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
exporters:
  debug:
    verbosity: detailed
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      exporters: [debug]
    logs:
      receivers: [otlp]
      exporters: [debug]

Now run the collector in a docker container:

docker run -p 4317:4317 -p 4318:4318 --rm -v $(pwd)/collector-config.yaml:/etc/otelcol/config.yaml otel/opentelemetry-collector

This collector is now able to accept telemetry via OTLP. Later you may want to configure the collector to send your telemetry to your observability backend.

Dependencies

If you want to send telemetry data to an OTLP endpoint (like the OpenTelemetry Collector, Jaeger or Prometheus), you can choose between three different protocols to transport your data:

• HTTP/protobuf
• HTTP/JSON
• gRPC

Start by installing the respective exporter packages as a dependency for your project:

• HTTP/Proto
• HTTP/JSON
• gRPC

npm install --save @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/exporter-metrics-otlp-proto

npm install --save @opentelemetry/exporter-trace-otlp-http \
  @opentelemetry/exporter-metrics-otlp-http

npm install --save @opentelemetry/exporter-trace-otlp-grpc \
  @opentelemetry/exporter-metrics-otlp-grpc

Usage with Node.js

Next, configure the exporter to point at an OTLP endpoint. For example you can update the file instrumentation.ts (or instrumentation.js if you use JavaScript) from the Getting Started like the following to export traces and metrics via OTLP (http/protobuf) :

• TypeScript
• JavaScript

/*instrumentation.ts*/
import * as opentelemetry from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-proto';
import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';

const sdk = new opentelemetry.NodeSDK({
  traceExporter: new OTLPTraceExporter({
    // optional - default url is http://localhost:4318/v1/traces
    url: '<your-otlp-endpoint>/v1/traces',
    // optional - collection of custom headers to be sent with each request, empty by default
    headers: {},
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: '<your-otlp-endpoint>/v1/metrics', // url is optional and can be omitted - default is http://localhost:4318/v1/metrics
      headers: {}, // an optional object containing custom headers to be sent with each request
    }),
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

/*instrumentation.js*/
const opentelemetry = require('@opentelemetry/sdk-node');
const {
  getNodeAutoInstrumentations,
} = require('@opentelemetry/auto-instrumentations-node');
const {
  OTLPTraceExporter,
} = require('@opentelemetry/exporter-trace-otlp-proto');
const {
  OTLPMetricExporter,
} = require('@opentelemetry/exporter-metrics-otlp-proto');
const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');

const sdk = new opentelemetry.NodeSDK({
  traceExporter: new OTLPTraceExporter({
    // optional - default url is http://localhost:4318/v1/traces
    url: '<your-otlp-endpoint>/v1/traces',
    // optional - collection of custom headers to be sent with each request, empty by default
    headers: {},
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: '<your-otlp-endpoint>/v1/metrics', // url is optional and can be omitted - default is http://localhost:4318/v1/metrics
      headers: {}, // an optional object containing custom headers to be sent with each request
      concurrencyLimit: 1, // an optional limit on pending requests
    }),
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

Usage in the Browser

When you use the OTLP exporter in a browser-based application, you need to note that:

1. Using gRPC for exporting is not supported
2. Content Security Policies (CSPs) of your website might block your exports
3. Cross-Origin Resource Sharing (CORS) headers might not allow your exports to be sent
4. You might need to expose your collector to the public internet

Below you will find instructions to use the right exporter, to configure your CSPs and CORS headers and what precautions you have to take when exposing your collector.

Use OTLP exporter with HTTP/JSON or HTTP/protobuf

OpenTelemetry Collector Exporter with gRPC works only with Node.js, therefore you are limited to use the OpenTelemetry Collector Exporter with HTTP/JSON or OpenTelemetry Collector Exporter with HTTP/protobuf.

Make sure that the receiving end of your exporter (collector or observability backend) accepts http/json if you are using OpenTelemetry Collector Exporter with HTTP/JSON, and that you are exporting your data to the right endpoint with your port set to 4318.

Configure CSPs

If your website is making use of Content Security Policies (CSPs), make sure that the domain of your OTLP endpoint is included. If your collector endpoint is https://collector.example.com:4318/v1/traces, add the following directive:

connect-src collector.example.com:4318/v1/traces

If your CSP is not including the OTLP endpoint, you will see an error message, stating that the request to your endpoint is violating the CSP directive.

Configure CORS headers

If your website and collector are hosted at a different origin, your browser might block the requests going out to your collector. You need to configure special headers for Cross-Origin Resource Sharing (CORS).

The OpenTelemetry Collector provides a feature for http-based receivers to add the required headers to allow the receiver to accept traces from a web browser:

receivers:
  otlp:
    protocols:
      http:
        include_metadata: true
        cors:
          allowed_origins:
            - https://foo.bar.com
            - https://*.test.com
          allowed_headers:
            - Example-Header
          max_age: 7200

Securely expose your collector

To receive telemetry from a web application you need to allow the browsers of your end-users to send data to your collector. If your web application is accessible from the public internet, you also have to make your collector accessible for everyone.

It is recommended that you do not expose your collector directly, but that you put a reverse proxy (NGINX, Apache HTTP Server, …) in front of it. The reverse proxy can take care of SSL-offloading, setting the right CORS headers, and many other features specific to web applications.

Below you will find a configuration for the popular NGINX web server to get you started:

server {
    listen 80 default_server;
    server_name _;
    location / {
        # Take care of preflight requests
        if ($request_method = 'OPTIONS') {
             add_header 'Access-Control-Max-Age' 1728000;
             add_header 'Access-Control-Allow-Origin' 'name.of.your.website.example.com' always;
             add_header 'Access-Control-Allow-Headers' 'Accept,Accept-Language,Content-Language,Content-Type' always;
             add_header 'Access-Control-Allow-Credentials' 'true' always;
             add_header 'Content-Type' 'text/plain charset=UTF-8';
             add_header 'Content-Length' 0;
             return 204;
        }

        add_header 'Access-Control-Allow-Origin' 'name.of.your.website.example.com' always;
        add_header 'Access-Control-Allow-Credentials' 'true' always;
        add_header 'Access-Control-Allow-Headers' 'Accept,Accept-Language,Content-Language,Content-Type' always;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://collector:4318;
    }
}

Console

To debug your instrumentation or see the values locally in development, you can use exporters writing telemetry data to the console (stdout).

If you followed the Getting Started or Manual Instrumentation guides, you already have the console exporter installed.

The ConsoleSpanExporter is included in the @opentelemetry/sdk-trace-node package and the ConsoleMetricExporter is included in the @opentelemetry/sdk-metrics package:

Jaeger

后端设置

Jaeger 原生支持 OTLP，用于接收链路（trace）数据。你可以通过运行一个 Docker 容器来启动 Jaeger，其 UI 默认在端口 16686 上可访问，并在端口 4317 和 4318 上启用 OTLP：

docker run --rm \
  -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 9411:9411 \
  jaegertracing/all-in-one:latest

使用方法

现在，按照说明设置 OTLP exporters。

Prometheus

要将你的指标（metrics）数据发送到 Prometheus， 你可以选择 启用 Prometheus 的 OTLP 接收器 并且使用 OTLP exporter，或者使用 Prometheus exporter，这是一种 MetricReader， 他启动一个 HTTP 服务器，根据请求收集指标并将数据序列化为 Prometheus 文本格式。

后端设置

你可以按照以下步骤在 Docker 容器中运行 Prometheus，并通过端口 9090 访问：

创建一个名为 prometheus.yml 的文件，并将以下内容写入文件：

scrape_configs:
  - job_name: dice-service
    scrape_interval: 5s
    static_configs:
      - targets: [host.docker.internal:9464]

使用以下命令在 Docker 容器中运行 Prometheus，UI 可通过端口 9090 访问：

docker run --rm -v ${PWD}/prometheus.yml:/prometheus/prometheus.yml -p 9090:9090 prom/prometheus --enable-feature=otlp-write-receive

Dependencies

Install the exporter package as a dependency for your application:

npm install --save @opentelemetry/exporter-prometheus

Update your OpenTelemetry configuration to use the exporter and to send data to your Prometheus backend:

• TypeScript
• JavaScript

import * as opentelemetry from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';

const sdk = new opentelemetry.NodeSDK({
  metricReader: new PrometheusExporter({
    port: 9464, // optional - default is 9464
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

const opentelemetry = require('@opentelemetry/sdk-node');
const {
  getNodeAutoInstrumentations,
} = require('@opentelemetry/auto-instrumentations-node');
const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus');
const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const sdk = new opentelemetry.NodeSDK({
  metricReader: new PrometheusExporter({
    port: 9464, // optional - default is 9464
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

With the above you can access your metrics at http://localhost:9464/metrics. Prometheus or an OpenTelemetry Collector with the Prometheus receiver can scrape the metrics from this endpoint.

Zipkin

后端设置

你可以通过执行以下命令，在 Docker 容器中运行 Zipkin：

docker run --rm -d -p 9411:9411 --name zipkin openzipkin/zipkin

Dependencies

To send your trace data to Zipkin, you can use the ZipkinExporter.

Install the exporter package as a dependency for your application:

npm install --save @opentelemetry/exporter-zipkin

Update your OpenTelemetry configuration to use the exporter and to send data to your Zipkin backend:

• TypeScript
• JavaScript

import * as opentelemetry from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { ZipkinExporter } from '@opentelemetry/exporter-zipkin';

const sdk = new opentelemetry.NodeSDK({
  traceExporter: new ZipkinExporter({}),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

const opentelemetry = require('@opentelemetry/sdk-node');
const {
  getNodeAutoInstrumentations,
} = require('@opentelemetry/auto-instrumentations-node');
const { ZipkinExporter } = require('@opentelemetry/exporter-zipkin');

const sdk = new opentelemetry.NodeSDK({
  traceExporter: new ZipkinExporter({}),
  instrumentations: [getNodeAutoInstrumentations()],
});

自定义导出器（Exporter）

最后，你还可以编写自己的导出器。有关更多信息，请参见 API 文档中的 SpanExporter 接口.

批量处理 Span 和日志记录

OpenTelemetry SDK 提供了一组默认的 span 和日志记录处理器，允许你选择按单条（simple）或按批量（batch）方式导出一个或多个 span。推荐使用批量处理，但如果你不想批量处理 span 或日志记录，可以使用 simple 处理器，方法如下：

• TypeScript
• JavaScript

/*instrumentation.ts*/
import * as opentelemetry from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

const sdk = new NodeSDK({
  spanProcessors: [new SimpleSpanProcessor(exporter)],
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

/*instrumentation.js*/
const opentelemetry = require('@opentelemetry/sdk-node');
const {
  getNodeAutoInstrumentations,
} = require('@opentelemetry/auto-instrumentations-node');

const sdk = new opentelemetry.NodeSDK({
  spanProcessors: [new SimpleSpanProcessor(exporter)],
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();