Configure o SDK

O SDK é a implementação de referência integrada da API, processando e exportando a telemetria produzida por chamadas da API de instrumentação. Configurar o SDK para processar e exportar corretamente é um passo essencial para integrar o OpenTelemetry a uma aplicação.

Todos os componentes do SDK possuem APIs de configuração programática. Essa é a forma mais flexível e expressiva de configurar o SDK. Contudo, alterar configurações exige ajustes no código e recompilar a aplicação, e não há interoperabilidade entre linguagens, já que a API é escrita em java.

O SDK de autoconfiguração sem código configura os componentes do SDK através de propriedades do sistema ou variáveis de ambiente, com diversos pontos de extensão para casos em que as propriedades não são suficientes.

Configuração programática

A interface de configuração programática é o conjunto de APIs para construir componentes do SDK. Todos os componentes do SDK possuem uma API de configuração programática, e todos os demais mecanismos de configuração são construídos sobre essa API. Por exemplo, a interface de configuração por variáveis de ambiente e propriedades do sistema interpreta variáveis e propriedades conhecidas e as traduz em chamadas à API de configuração programática.

Embora outros mecanismos de configuração sejam mais convenientes, nenhum oferece a mesma flexibilidade de escrever código que expressa exatamente a configuração necessária. Quando um determinado recurso não é suportado por um mecanismo de configuração de nível mais alto, talvez não haja outra opção além de usar configuração programática.

As seções de componentes do SDK demonstram uma API de configuração programática simples para as principais áreas voltadas ao usuário do SDK. Consulte o código para obter a referência completa da API.

Autoconfiguração sem código do SDK

O módulo de autoconfiguração (artefato io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.55.0) é uma interface de configuração construída sobre a interface de configuração programática, que configura componentes do SDK sem escrever código. Existem dois fluxos distintos de autoconfiguração:

• Variáveis de ambiente e propriedades do sistema interpretam variáveis de ambiente e propriedades do sistema para criar componentes do SDK, incluindo pontos de personalização para sobrepor a configuração programática.
• Configuração declarativa (em desenvolvimento) interpreta um modelo de configuração para criar componentes do SDK, que é tipicamente codificado em um arquivo YAML.

Configure automaticamente componentes do SDK com autoconfiguração da seguinte maneira:

package otel;

import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

public class AutoConfiguredSdk {
  public static OpenTelemetrySdk autoconfiguredSdk() {
    return AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();
  }
}

Variáveis de ambiente e propriedades do sistema

O módulo de autoconfiguração oferece suporte às propriedades listadas na especificação de configuração por variáveis de ambiente, com algumas adições experimentais e específicas do Java.

As propriedades a seguir são apresentadas como propriedades do sistema, mas também podem ser definidas por meio de variáveis de ambiente. Siga os passos abaixo para converter uma propriedade de sistema em uma variável de ambiente:

• Converta o nome para letras maiúsculas.
• Substitua todos os caracteres . e - por _.

Por exemplo, a propriedade de sistema otel.sdk.disabled é equivalente à variável de ambiente OTEL_SDK_DISABLED.

Se uma propriedade for definida tanto como propriedade de sistema quanto como variável de ambiente, a propriedade de sistema terá prioridade.

Propriedades: gerais

Propriedades para desabilitar o SDK:

[1]: Se desabilitado, AutoConfiguredOpenTelemetrySdk#getOpenTelemetrySdk() retorna uma instância minimamente configurada (por exemplo, OpenTelemetrySdk.builder().build()).

Propriedades para limites de atributos (veja limites de trecho, limites de log):

Propriedades para propagação de contexto:

[1]: Propagadores e artefatos conhecidos (veja propagador de mapa de texto para coordenadas de artefatos):

• tracecontext configura W3CTraceContextPropagator.
• baggage configura W3CBaggagePropagator.
• b3, b3multi configura B3Propagator.
• jaeger configura JaegerPropagator.
• ottrace configura OtTracePropagator.
• xray configura AwsXrayPropagator.
• xray-lambda configura AwsXrayLambdaPropagator.

Propriedades: recurso

Propriedades para configurar recurso:

[1]: Por exemplo, para desabilitar o provedor de recursos do sistema operacional, defina -Dotel.java.disabled.resource.providers=io.opentelemetry.instrumentation.resources.OsResourceProvider.

NOTA: As propriedades de sistema / variáveis de ambiente otel.service.name e otel.resource.attributes são interpretadas pelo provedor de recurso io.opentelemetry.sdk.autoconfigure.EnvironmentResourceProvider. Se você optar por definir provedores de recurso via otel.java.enabled.resource-providers, é recomendável incluir este provedor para evitar comportamentos inesperados. Consulte ResourceProvider para as coordenadas dos artefatos de provedores de recurso.

Propriedades: rastros

Propriedades para processadores de rastros em lote usado em conjunto com os exportadores definidos por meio de otel.traces.exporter:

Propriedades para o amostrador (sampler):

[1]: Amostradores e artefatos conhecidos (consulte amostrador para coordenadas de artefatos):

• always_on configura AlwaysOnSampler.
• always_off configura AlwaysOffSampler.
• traceidratio configura TraceIdRatioBased; otel.traces.sampler.arg define a taxa de amostragem.
• parentbased_always_on configura ParentBased(root=AlwaysOnSampler).
• parentbased_always_off configura ParentBased(root=AlwaysOffSampler).
• parentbased_traceidratio configura ParentBased(root=TraceIdRatioBased); otel.traces.sampler.arg define a taxa de amostragem.
• jaeger_remote configura JaegerRemoteSampler; otel.traces.sampler.arg é uma lista separada por vírgulas, conforme descrito na especificação.

Propriedades para limites de trechos:

Propriedades: métricas

Propriedades para leitor de métricas periódico:

Propriedades para exemplares:

Propriedades para limites de cardinalidade:

Propriedades: logs

Propriedades para o processador de registros de log usado junto com os exportadores definidos via otel.logs.exporter:

Propriedades: exportadores

Propriedades para configurar exportadores (exporters):

[1]: Exportadores e artefatos conhecidos (consulte SpanExporter, MetricExporter, LogExporter para coordenadas dos artefatos):

• otlp configura OtlpHttp{Signal}Exporter / OtlpGrpc{Signal}Exporter.
• zipkin configura ZipkinSpanExporter.
• console configura LoggingSpanExporter, LoggingMetricExporter, SystemOutLogRecordExporter.
• logging-otlp configura OtlpJsonLogging{Signal}Exporter.
• experimental-otlp/stdout configura OtlpStdout{Signal}Exporter ( esta opção é experimental e pode mudar ou ser removida).

[2]: Os exportadores que suportam otel.java.exporter.memory_mode=reusable_data são OtlpGrpc{Signal}Exporter, OtlpHttp{Signal}Exporter, OtlpStdout{Signal}Exporter, e PrometheusHttpServer.

Propriedades para exportadores otlp de rastros, métricas e logs:

| Propriedade do sistema | Descrição | Padrão | | Propriedade do sistema | Descrição | Padrão | | ——————————– |

| ————— | | otel.{sinal}.exporter=otlp | Seleciona o exportador OpenTelemetry para {sinal}. | | | otel.exporter.otlp.protocol | Protocolo de transporte usado nas requisições OTLP de rastros, métricas e logs. Opções: grpc e http/protobuf. | grpc [1] | | otel.exporter.otlp.{sinal}.protocol | Protocolo de transporte usado nas requisições OTLP de {sinal}. Opções: grpc e http/protobuf. | grpc [1] | | otel.exporter.otlp.endpoint | Rota para envio de rastros, métricas e logs OTLP. Normalmente o endereço de um Collector OpenTelemetry. Deve ser uma URL com esquema http ou https, conforme o uso de TLS. | http://localhost:4317 para o protocolo grpc ou http://localhost:4318 para o protocolo http/protobuf. | | otel.exporter.otlp.{sinal}.endpoint | Rota para envio de {sinal} via OTLP. Normalmente o endereço de um Collector OpenTelemetry. Se o protocolo for http/protobuf, o caminho deve incluir a versão e o tipo de sinal (por exemplo, v1/traces, v1/metrics, ou v1/logs). | http://localhost:4317 quando o protocolo for grpc, e http://localhost:4318/v1/{signal} quando o protocolo for http/protobuf. | | otel.exporter.otlp.certificate | O caminho para o arquivo contendo certificados confiáveis para usar ao verificar as credenciais TLS do servidor do OTLP de rastros, métricas ou logs. O arquivo deve conter um ou mais certificados X.509 no formato PEM. | Os certificados raiz confiáveis do host são usados. | | otel.exporter.otlp.{signal}.certificate | O caminho para o arquivo contendo certificados confiáveis para usar ao verificar as credenciais TLS do servidor do OTLP de {signal}. O arquivo deve conter um ou mais certificados X.509 no formato PEM. | Os certificados raiz confiáveis do host são usados | | otel.exporter.otlp.client.key | O caminho para o arquivo contendo a chave privada do cliente para usar ao verificar as credenciais TLS do cliente do OTLP de rastros, métricas ou logs. O arquivo deve conter uma chave privada PKCS8 no formato PEM. | Nenhum arquivo de chave privada do cliente é usado. | | otel.exporter.otlp.{signal}.client.key | O caminho para o arquivo contendo a chave privada do cliente para usar ao verificar as credenciais TLS do cliente do OTLP de {signal}. O arquivo deve conter uma chave privada PKCS8 no formato PEM. | Nenhum arquivo de chave privada do cliente é usado. | | otel.exporter.otlp.client.certificate | O caminho para o arquivo contendo certificados confiáveis para usar ao verificar as credenciais TLS do cliente do OTLP de rastros, métricas ou logs. O arquivo deve conter um ou mais certificados X.509 no formato PEM. | Nenhum arquivo de cadeia é usado. | | otel.exporter.otlp.{signal}.client.certificate | O caminho para o arquivo contendo certificados confiáveis para usar ao verificar as credenciais TLS do cliente do OTLP de {signal}. O arquivo deve conter um ou mais certificados X.509 no formato PEM. | Nenhum arquivo de cadeia é usado. | | otel.exporter.otlp.headers | Pares de chave-valor separados por vírgula para passar como cabeçalhos de requisição no envio de rastros, métricas e logs OTLP. | | | otel.exporter.otlp.{signal}.headers | Pares de chave-valor separados por vírgula para passar como cabeçalhos de requisição no envio de {signal} OTLP. | | | otel.exporter.otlp.compression | O tipo de compressão a ser usado no envio de rastros, métricas e logs OTLP. Opções incluem gzip. | Nenhuma compressão será usada. | | otel.exporter.otlp.{signal}.compression | O tipo de compressão a ser usado no envio de {signal} OTLP. Opções incluem gzip. | Nenhuma compressão será usada. | | otel.exporter.otlp.timeout | O tempo máximo de espera, em milissegundos, permitido para enviar cada lote de rastros, métricas e logs OTLP. | 10000 | | otel.exporter.otlp.{signal}.timeout | O tempo máximo de espera, em milissegundos, permitido para enviar cada lote de {signal} OTLP. | 10000 | | otel.exporter.otlp.metrics.temporality.preference | Temporalidade de agregação preferida na saída. Opções incluem DELTA, LOWMEMORY, e CUMULATIVE. Quando definido CUMULATIVE, todos os instrumentos terão temporalidade cumulativa. Quando definido DELTA, contadores (síncronos e assíncronos) e histogramas serão delta, contadores up down (síncronos e assíncronos) serão cumulativos. Quando definido LOWMEMORY, contadores síncronos e histogramas serão delta, contadores assíncronos e contadores up down (síncronos e assíncronos) serão cumulativos. | CUMULATIVE | | otel.exporter.otlp.metrics.default.histogram.aggregation | Agregação padrão preferida para histogramas. Opções incluem BASE2_EXPONENTIAL_BUCKET_HISTOGRAM e EXPLICIT_BUCKET_HISTOGRAM. | EXPLICIT_BUCKET_HISTOGRAM | | otel.java.exporter.otlp.retry.disabled | Quando false, faz retry quando ocorrem erros transitórios. [2] | false |

NOTA: O marcador {sinal} refere-se aos Sinais do OpenTelemetry. Valores válidos incluem traces, metrics e logs. Configurações específicas do sinal têm prioridade sobre as genéricas. Por exemplo, se você definir tanto otel.exporter.otlp.endpoint quanto otel.exporter.otlp.traces.endpoint, a segunda definição terá precedência.

[1]: O agente OpenTelemetry Java 2.x e o inicializador Spring Boot (Spring Boot starter) usam http/protobuf por padrão.

[2]: O OTLP exige que erros transitório sejam tratados com estratégias de retry. Quando o retry está habilitado, códigos gRPC retryable são repetidos usando exponential backoff com jitter. As opções específicas de RetryPolicy só podem ser personalizadas via personalização programática.

Propriedades para exportador de trechos zipkin:

Propriedades para exportador de métricas prometheus:

Personalização programática

A personalização programática fornece hooks para complementar as propriedades suportadas com configuração programática.

Se estiver usando o inicializador Spring, consulte também a seção de configuração programática do inicializador Spring.

package otel;

import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;
import java.util.Collections;

public class CustomizedAutoConfiguredSdk {
  public static OpenTelemetrySdk autoconfiguredSdk() {
    return AutoConfiguredOpenTelemetrySdk.builder()
        // Opcionalmente, personaliza o TextMapPropagator.
        .addPropagatorCustomizer((textMapPropagator, configProperties) -> textMapPropagator)
        // Opcionalmente, personaliza o Resource.
        .addResourceCustomizer((resource, configProperties) -> resource)
        // Opcionalmente, personaliza o Sampler.
        .addSamplerCustomizer((sampler, configProperties) -> sampler)
        // Opcionalmente, personaliza o SpanExporter.
        .addSpanExporterCustomizer((spanExporter, configProperties) -> spanExporter)
        // Opcionalmente, personaliza o SpanProcessor.
        .addSpanProcessorCustomizer((spanProcessor, configProperties) -> spanProcessor)
        // Opcionalmente, forneça propriedades adicionais.
        .addPropertiesSupplier(Collections::emptyMap)
        // Opcionalmente, personaliza o ConfigProperties.
        .addPropertiesCustomizer(configProperties -> Collections.emptyMap())
        // Opcionalmente, personaliza o SdkTracerProviderBuilder.
        .addTracerProviderCustomizer((builder, configProperties) -> builder)
        // Opcionalmente, personaliza o SdkMeterProviderBuilder.
        .addMeterProviderCustomizer((builder, configProperties) -> builder)
        // Opcionalmente, personaliza o MetricExporter.
        .addMetricExporterCustomizer((metricExporter, configProperties) -> metricExporter)
        // Opcionalmente, personaliza o MetricReader.
        .addMetricReaderCustomizer((metricReader, configProperties) -> metricReader)
        // Opcionalmente, personaliza o SdkLoggerProviderBuilder.
        .addLoggerProviderCustomizer((builder, configProperties) -> builder)
        // Opcionalmente, personaliza o LogRecordExporter.
        .addLogRecordExporterCustomizer((logRecordExporter, configProperties) -> logRecordExporter)
        // Opcionalmente, personaliza o LogRecordProcessor.
        .addLogRecordProcessorCustomizer((processor, configProperties) -> processor)
        .build()
        .getOpenTelemetrySdk();
  }
}

SPI (Service provider interface)

SPIs (artefato io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi:1.55.0) estendem a autoconfiguração do SDK além dos componentes embutidos no próprio SDK.

As seções a seguir descrevem os SPIs disponíveis. Cada seção inclui:

• Uma breve descrição, com link para o tipo na Javadoc.
• Uma tabela de implementações embutidas e do opentelemetry-java-contrib.
• Um exemplo simples de implementação personalizada.

ResourceProvider

ResourceProviders contribuem para o recurso autoconfigurado.

ResourceProviders embutidos no SDK e mantidos pela comunidade em opentelemetry-java-contrib:

Implemente a interface ResourceProvider para participar da autoconfiguração de recurso. Por exemplo:

package otel;

import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.ResourceProvider;
import io.opentelemetry.sdk.resources.Resource;

public class CustomResourceProvider implements ResourceProvider {

  @Override
  public Resource createResource(ConfigProperties config) {
    // Callback invocado para contribuir com o recurso.
    return Resource.builder().put("my.custom.resource.attribute", "abc123").build();
  }

  @Override
  public int order() {
    // Opcionalmente, influencie a ordem de invocação.
    return 0;
  }
}

AutoConfigurationCustomizerProvider

Implemente a interface AutoConfigurationCustomizerProvider para personalizar uma variedade de componentes autoconfigurados do SDK. Por exemplo:

package otel;

import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizer;
import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider;
import java.util.Collections;

public class CustomizerProvider implements AutoConfigurationCustomizerProvider {

  @Override
  public void customize(AutoConfigurationCustomizer customizer) {
    // Opcionalmente, personalize o TextMapPropagator.
    customizer.addPropagatorCustomizer((textMapPropagator, configProperties) -> textMapPropagator);
    // Opcionalmente, personalize o Resource.
    customizer.addResourceCustomizer((resource, configProperties) -> resource);
    // Opcionalmente, personalize o Sampler.
    customizer.addSamplerCustomizer((sampler, configProperties) -> sampler);
    // Opcionalmente, personalize o SpanExporter.
    customizer.addSpanExporterCustomizer((spanExporter, configProperties) -> spanExporter);
    // Opcionalmente, personalize o SpanProcessor.
    customizer.addSpanProcessorCustomizer((spanProcessor, configProperties) -> spanProcessor);
    // Optionally supply additional properties.
    customizer.addPropertiesSupplier(Collections::emptyMap);
    // Opcionalmente, personalize o ConfigProperties.
    customizer.addPropertiesCustomizer(configProperties -> Collections.emptyMap());
    // Opcionalmente, personalize o SdkTracerProviderBuilder.
    customizer.addTracerProviderCustomizer((builder, configProperties) -> builder);
    // Opcionalmente, personalize o SdkMeterProviderBuilder.
    customizer.addMeterProviderCustomizer((builder, configProperties) -> builder);
    // Opcionalmente, personalize o MetricExporter.
    customizer.addMetricExporterCustomizer((metricExporter, configProperties) -> metricExporter);
    // Opcionalmente, personalize o MetricReader.
    customizer.addMetricReaderCustomizer((metricReader, configProperties) -> metricReader);
    // Opcionalmente, personalize o SdkLoggerProviderBuilder.
    customizer.addLoggerProviderCustomizer((builder, configProperties) -> builder);
    // Opcionalmente, personalize o LogRecordExporter.
    customizer.addLogRecordExporterCustomizer((exporter, configProperties) -> exporter);
    // Opcionalmente, personalize o LogRecordProcessor.
    customizer.addLogRecordProcessorCustomizer((processor, configProperties) -> processor);
  }

  @Override
  public int order() {
    // Opcionalmente, influencie a ordem de invocação.
    return 0;
  }
}

ConfigurableSpanExporterProvider

Implemente a interface ConfigurableSpanExporterProvider para permitir que um exportador de trecho personalizado participe da autoconfiguração. Por exemplo:

package otel;

import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.traces.ConfigurableSpanExporterProvider;
import io.opentelemetry.sdk.trace.export.SpanExporter;

public class CustomSpanExporterProvider implements ConfigurableSpanExporterProvider {

  @Override
  public SpanExporter createExporter(ConfigProperties config) {
    // Callback invocado quando OTEL_TRACES_EXPORTER inclui o valor de getName().
    return new CustomSpanExporter();
  }

  @Override
  public String getName() {
    return "custom-exporter";
  }
}

ConfigurableMetricExporterProvider

Implemente a interface ConfigurableMetricExporterProvider para permitir que um exportador de métrica personalizado participe da autoconfiguração. Por exemplo:

package otel;

import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.metrics.ConfigurableMetricExporterProvider;
import io.opentelemetry.sdk.metrics.export.MetricExporter;

public class CustomMetricExporterProvider implements ConfigurableMetricExporterProvider {

  @Override
  public MetricExporter createExporter(ConfigProperties config) {
    // Callback invocado quando OTEL_METRICS_EXPORTER inclui o valor de getName().
    return new CustomMetricExporter();
  }

  @Override
  public String getName() {
    return "custom-exporter";
  }
}

ConfigurableLogRecordExporterProvider

Implemente a interface ConfigurableLogRecordExporterProvider para permitir que um exportador de registro de log personalizado participe da autoconfiguração. Por exemplo:

package otel;

import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.logs.ConfigurableLogRecordExporterProvider;
import io.opentelemetry.sdk.logs.export.LogRecordExporter;

public class CustomLogRecordExporterProvider implements ConfigurableLogRecordExporterProvider {

  @Override
  public LogRecordExporter createExporter(ConfigProperties config) {
    // Callback invocado quando OTEL_LOGS_EXPORTER inclui o valor de getName().
    return new CustomLogRecordExporter();
  }

  @Override
  public String getName() {
    return "custom-exporter";
  }
}

ConfigurableSamplerProvider

Implemente a interface ConfigurableSamplerProvider para permitir que um sampler personalizado participe da autoconfiguração. Por exemplo:

package otel;

import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.traces.ConfigurableSamplerProvider;
import io.opentelemetry.sdk.trace.samplers.Sampler;

public class CustomSamplerProvider implements ConfigurableSamplerProvider {

  @Override
  public Sampler createSampler(ConfigProperties config) {
    // Callback invocado quando OTEL_TRACES_SAMPLER é definido para o valor de getName().
    return new CustomSampler();
  }

  @Override
  public String getName() {
    return "custom-sampler";
  }
}

ConfigurablePropagatorProvider

Implemente a interface ConfigurablePropagatorProvider para permitir que um propagador personalizado participe da autoconfiguração. Por exemplo:

package otel;

import io.opentelemetry.context.propagation.TextMapPropagator;
import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.ConfigurablePropagatorProvider;

public class CustomTextMapPropagatorProvider implements ConfigurablePropagatorProvider {
  @Override
  public TextMapPropagator getPropagator(ConfigProperties config) {
    // Callback invocado quando OTEL_PROPAGATORS inclui o valor de getName().
    return new CustomTextMapPropagator();
  }

  @Override
  public String getName() {
    return "custom-propagator";
  }
}

Configuração declarativa

A configuração declarativa está em desenvolvimento. Ela permite configuração baseada em arquivo YAML, conforme descrito em opentelemetry-configuration e em configuração declarativa.

Para utilizar, inclua io.opentelemetry:opentelemetry-sdk-extension-incubator:1.55.0-alpha e especifique o caminho para o arquivo de configuração conforme descrito na tabela abaixo.

Para mais detalhes, consulte os seguintes recursos:

• Documentação de uso
• Exemplo com agente Java
• Exemplo sem agente Java