Exporters

Envie dados de telemetria para o OpenTelemetry Collector para garantir que estes dados sejam exportados corretamente. A utilização de um Collector em ambientes de produção é a melhor prática. Para visualizar os dados de telemetria que foram gerados, exporte-os para um backend como Jaeger, Zipkin, Prometheus, ou um backend específico de um fornecedor.

Exportadores disponíveis

O registro oferece uma lista de exportadores para JavaScript.

Entre os exportadores, os exportadores do OpenTelemetry Protocol (OTLP) são projetados tendo em mente o modelo de dados do OpenTelemetry, emitindo dados OTel sem qualquer perda de informação. Além disso, muitas ferramentas que operam com dados de telemetria suportam o formato OTLP (como Prometheus, Jaeger e a maioria dos fornecedores), proporcionando um alto grau de flexibilidade quando necessário. Para saber mais sobre o OTLP, consulte a Especificação do OTLP.

Esta página reúne informações sobre os principais exportadores do OpenTelemetry JavaScript e como configurá-los.

OTLP

Configuração do Collector

Para testar e validar os seus exportadores OTLP, é possível executar o Collector em um contêiner Docker que escreve os dados diretamente no console.

Em uma pasta vazia, crie um arquivo chamado collector-config.yaml e adicione o seguinte conteúdo:

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]

Em seguida, execute o Collector em um contêiner Docker através do seguinte comando:

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

Este Collector agora é capaz receber dados de telemetria via OTLP. Mais tarde, você também poderá configurar o Collector para enviar os seus dados de telemetria para o seu backend de observabilidade.

Dependências

Caso queira enviar dados de telemetria para uma rota OTLP (como o OpenTelemetry Collector, Jaeger ou Prometheus), é possível escolher entre três protocolos diferentes para transportar seus dados:

• HTTP/protobuf
• HTTP/JSON
• gRPC

Comece instalando os respectivos pacotes exportadores como dependência do seu projeto:

• 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

Uso com Node.js

Em seguida, configure o exportador para apontar para uma rota OTLP. Por exemplo, você pode atualizar o arquivo instrumentation.ts (ou instrumentation.js caso utilize JavaScript) do guia de Primeiros Passos para exportar rastros e métricas 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({
    // opcional - a URL padrão é http://localhost:4318/v1/traces
    url: '<sua-rota-otlp>/v1/traces',
    // opcional - coleção de cabeçalhos (headers) personalizados a serem enviados com cada requisição, vazio por padrão
    headers: {},
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: '<sua-rota-otlp>/v1/metrics', // a URL é opcional e pode ser omitida - o padrão é http://localhost:4318/v1/metrics
      headers: {}, // um objeto opcional contendo cabeçalhos personalizados a serem enviados com cada requisição
    }),
  }),
  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({
    // opcional - a URL padrão é http://localhost:4318/v1/traces
    url: '<sua-rota-otlp>/v1/traces',
    // opcional - coleção de cabeçalhos (headers) personalizados a serem enviados com cada requisição, vazio por padrão
    headers: {},
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: '<sua-rota-otlp>/v1/metrics', // a URL é opcional e pode ser omitida - o padrão é http://localhost:4318/v1/metrics
      headers: {}, // um objeto opcional contendo cabeçalhos personalizados a serem enviados com cada requisição
      concurrencyLimit: 1, // um limite opcional para requisições pendentes
    }),
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

Uso no navegador

Ao utilizar o exportador OTLP em uma aplicação baseada em navegador, é importante considerar:

1. Exportação via gRPC não é suportada
2. As Políticas de Segurança de Conteúdo (Content Security Policies, ou CSPs) do seu site podem bloquear as exportações
3. Os cabeçalhos de Compartilhamento de recursos com origens diferentes (Cross-Origin Resource Sharing, ou CORS) podem não permitir que suas exportações sejam enviadas
4. Talvez seja necessário expor seu Collector publicamente na internet

Abaixo você encontrará instruções para escolher o exportador correto, configurar CSPs e cabeçalhos CORS, e entender quais precauções você deve tomar ao expor seu Collector.

Usar exportador OTLP com HTTP/JSON ou HTTP/protobuf

O OpenTelemetry Collector Exporter com gRPC funciona apenas com Node.js; portanto, fica limitado ao uso do OpenTelemetry Collector Exporter com HTTP/JSON ou OpenTelemetry Collector Exporter com HTTP/protobuf.

Certifique-se de que o destino do seu exportador (Collector ou backend de observabilidade) aceite http/json caso você esteja utilizando o OpenTelemetry Collector Exporter com HTTP/JSON, e que os dados estejam sendo exportados para a rota correta, com a porta definida como 4318.

Configurar CSPs

Caso seu site utilize Políticas de Segurança de Conteúdo (Content Security Policies, ou CSPs), certifique-se de que o domínio da sua rota OTLP esteja incluído. Caso a rota do Collector seja https://collector.example.com:4318/v1/traces, adicione a seguinte diretiva:

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

Caso sua CSP não inclua a rota OTLP, você verá uma mensagem de erro informando que a requisição para sua rota está violando a diretiva CSP.

Configurar cabeçalhos CORS

Caso seu site e o Collector estejam hospedados em origens diferentes, seu navegador pode bloquear as requisições enviadas ao Collector. É necessário configurar cabeçalhos especiais para o Compartilhamento de Recursos com Origens Diferentes (Cross-Origin Resource Sharing, ou CORS).

O OpenTelemetry Collector fornece um recurso para receptores baseados em HTTP para adicionar os cabeçalhos necessários e permitir que o receptor aceite rastros de um navegador web:

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

Expor seu Collector com segurança

Para receber telemetria de uma aplicação web, é necessário permitir que os navegadores dos seus usuários finais enviem dados para o seu Collector. Caso sua aplicação web esteja acessível pela internet pública, também é necessário tornar seu Collector acessível para todos.

É recomendado que o Collector não seja exposto diretamente, mas que você utilize um proxy reverso (NGINX, Apache HTTP Server, …) na frente dele. O proxy reverso pode cuidar do SSL-offloading, definir os cabeçalhos CORS corretos, e muitas outras funcionalidades específicas para aplicações web.

Abaixo você encontra uma configuração inicial para o servidor NGINX:

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' 'nome.do.seu.website.exemplo.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' 'nome.do.seu.website.exemplo.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

Para depurar (debug) sua instrumentação ou visualizar valores localmente durante o desenvolvimento, é possível utilizar exportadores que escrevem dados de telemetria no console (stdout).

Se você seguiu o guia em Primeiros Passos ou Instrumentação Manual, você já tem o exportador de console instalado.

O ConsoleSpanExporter está incluído no pacote @opentelemetry/sdk-trace-node, e o ConsoleMetricExporter está incluído no pacote @opentelemetry/sdk-metrics:

Jaeger

Configuração do Backend

O Jaeger suporta nativamente o OTLP para receber dados de rastros. O Jaeger pode ser executado através de um contêiner Docker com uma UI acessível através da porta 16686 e OTLP habilitados nas portas 4317 e 4318:

docker run --rm \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 9411:9411 \
  jaegertracing/jaeger:latest

Uso

Siga as instruções para configurar os exportadores OTLP.

Prometheus

Para enviar dados de métricas para o Prometheus, você pode:

• Ativar o OTLP Receiver do Prometheus e utilizar o exportador OTLP (boa prática), ou
• Utilizar o exportador do Prometheus, um MetricReader que inicia um servidor HTTP e coleta métricas, serializando para o formato de texto do Prometheus sob demanda.

Configuração do backend

Para executar um servidor Prometheus como backend e começar a coletar métricas, consulte o guia de primeiros passos do Prometheus.

Para ativar o OTLP Receiver, consulte o guia do Prometheus para ativar o OTLP Receiver.

Dependências

Instale o pacote do exportador como uma dependência para sua aplicação:

npm install --save @opentelemetry/exporter-prometheus

Atualize sua configuração do OpenTelemetry para utilizar o exportador e enviar dados de telemetria para seu backend Prometheus:

• 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, // opcional - padrão é 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, // opcional - padrão é 9464
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

Com a configuração acima, é possível acessar suas métricas em http://localhost:9464/metrics. O Prometheus ou um OpenTelemetry Collector com o receptor Prometheus podem coletar as métricas desta rota.

Zipkin

Configuração do Backend

É possível executar o Zipkin em um contêiner Docker através do seguinte comando:

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

Dependências

Para enviar seus dados de rastros para o Zipkin, é possível utilizar o ZipkinExporter.

Instale o pacote do exportador como uma dependência para sua aplicação:

npm install --save @opentelemetry/exporter-zipkin

Atualize sua configuração do OpenTelemetry para utilizar o exportador e enviar dados para seu backend Zipkin:

• 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()],
});
sdk.start();

Exportadores personalizados

Por fim, também é possível escrever o seu próprio exportador. Para mais informações, consulte SpanExporter Interface na documentação da API.

Agrupamento de trechos e registros de log

O SDK do OpenTelemetry fornece um conjunto de processadores padrão de trechos e registros de log, que permitem emitir trechos um-a-um (“simples”) ou em lotes. O uso de agrupamentos é recomendado, mas caso não deseje agrupar seus trechos ou registros de log, é possível utilizar um processador simples da seguinte forma:

• 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();