Exporters

Processe e exporte seus dados de telemetria

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.

Nota

Caso você esteja utilizando instrumentação sem código, você poderá aprender a configurar os exporters através do Guia de Configurações.

OTLP

Configuração do Collector

Nota

Caso já possua um coletor ou backend OTLP configurado, poderá pular para configurar as dependências do exportador OTLP para a sua aplicação.

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:

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

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):

/*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:

Exportação via gRPC não é suportada
As Políticas de Segurança de Conteúdo (Content Security Policies, ou CSPs) do seu site podem bloquear as exportações
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
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 \
  -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 9411:9411 \
  jaegertracing/all-in-one: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 ou você pode 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

Nota

Caso já possua o Prometheus ou um backend compatível com Prometheus configurado, poderá pular esta seção e configurar as dependências do exportador Prometheus ou OTLP para a sua aplicação.

É possível executar o Prometheus em um contêiner Docker acessível na porta 9090 através das seguintes instruções:

Em uma pasta vazia, crie um arquivo chamado prometheus.yml e adicione o seguinte conteúdo:

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

Em seguida, execute o Prometheus em um contêiner Docker que ficará acessível na porta 9090 através do seguinte comando:

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

Nota

Ao utilizar o OTLP Receiver do Prometheus, certifique-se de definir o endpoint OTLP das métricas em sua aplicação para http://localhost:9090/api/v1/otlp.

Nem todos os ambientes Docker suportam host.docker.internal. Em alguns casos, será necessário alterar o valor host.docker.internal para localhost ou o endereço de IP de sua máquina.

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:

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

Nota

Caso já possua o Zipkin ou um backend compatível com Zipkin configurado, poderá pular esta seção e configurar as dependências do exportador Zipkin para a sua aplicação.

É possível executar o [Zipkin]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:

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:

/*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();

Feedback

Esta página foi útil?

Thank you. Your feedback is appreciated!

Please let us know how we can improve this page. Your feedback is appreciated!

Última modificação November 26, 2025: [pt] Localize content/pt/docs/languages/js/exporters.md (#8408) (a39f2f9f)