Configure o SDK

O SDK é a implementação de referência integrada da API, processando e exportando telemetrias produzidas pelas chamadas de instrumentação. Configurar o SDK para processar e exportar apropriadamente é um passo essencial para integrar o OpenTelemetry na sua aplicação.

Todos os componentes do SDK possuem APIs de configurações via código (configuração programática). É o caminho mais flexível e expressivo para configurar o SDK. No entanto, alterar as configurações requer ajustes no código e recompilar a aplicação, e não possui interoperabilidade na linguagem desde que a API seja escrita em Java.

O módulo de auto configuração sem código configura os componentes do SDK através de propriedades do sistema ou variáveis de ambiente, com vários pontos de extensão para instâncias onde as propriedades são insuficientes.

configuração programática

A interface de configuração via código (configuração programática) é um conjunto de APIs para construir componentes do SDK. Todos os componentes do SDK possuem APIs de configurações via código, e todos os outros mecanismos de configurações são implementados no inicio da API. Por exemplo, a interface de configuração auto configuração de variáveis de ambiente e propriedades do sistema interpreta as variáveis de ambiente e propriedades do sistema conhecidas em uma série de chamadas para a API.

Enquanto outros mecânicos de configurações oferecem mais conveniência, nenhum oferece a flexibilidade de escrever código que expresse com precisão as configurações necessárias. Quando uma capacidade especifica não é suportada por mecanismos de configuração de alto nível, pode ser necessário recorrer à configuração via código.

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

auto configuração sem código

O módulo de auto configuração (artifact io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.51.0) é uma interface de configuração construída sobre a, interface de configuração via código, que configura os componentes do SDK sem código. Eles possuem dois fluxos de auto configuração distintos:

• Variáveis de ambiente e propriedades do sistema interpreta variáveis de ambiente e propriedades do sistema para criar componentes do SDK, incluindo diversos pontos de customizações para sobrescrever configurações via código (configuração programática).
• Configurações declarativas (atualmente está em desenvolvimento) interpreta um modelo de configuração para criar os componentes do SDK, que normalmente é codificado em um arquivo de configuração YAML.

Automaticamente configura os componentes do SDK usando auto configurações descritas abaixo:

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 auto configuração suporta propriedades listadas em especificação de configuração por variável de ambiente, com algumas adições experimentais e específicas para Java.

As propriedades a seguir são listadas como propriedades do sistema, mas também podem ser definidas usando variáveis de ambiente. Aplique os passos a seguir para converter propriedades do sistema em variáveis de ambiente:

• Converta os nomes para maiúsculo.
• Substitua todos os . e - com _.

Por exemplo, a propriedade do sistema otel.sdk.enabled é equivalente à variável de ambiente OTEL_SDK_ENABLED.

Se a propriedade é definida como uma propriedade do sistema e variável de ambiente, a propriedade do sistema irá ser prioritaria.

Propriedades: geral

Propriedades para desativar o SDK:

[1]: Se desativado, AutoConfiguredOpenTelemetrySdk#getOpenTelemetrySdk() retorna uma configuração minima da instância (por exemplo, OpenTelemetrySdk.builder().build()).

Propriedades para limites de atributos (Veja limites de trechos, limites de logs):

Propriedades para propagação de contexto:

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

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

Propriedades: recursos

Propriedades para configurar recursos:

[1]: Por exemplo, para desabilitar o OS resource provider, defina -Dotel.java.disabled.resource.providers=io.opentelemetry.instrumentation.resources.OsResourceProvider.

NOTE: As propriedades do sistema / variáveis de ambiente otel.service.name e otel.resource.attributes pelo provedor de recurso io.opentelemetry.sdk.autoconfigure.EnvironmentResourceProvider. Se optar por especificar o provedor de recursos via otel.java.enabled.resource-providers, provavelmente você vai querer incluí-lo para evitar surpresas. Veja Provedor de Recursospara coordenadas de artefato do provedor de recurso.

Propriedades: traços

Propriedades para processadores em lote de trechos em conjunto com exportadores especificados via otel.traces.exporter:

Propriedades para Amostras:

[1]: Amostragens conhecidas e artefatos (veja sampler para artifact coordinates):

• always_on configura AlwaysOnSampler.
• always_off configura AlwaysOffSampler.
• traceidratio configura TraceIdRatioBased. otel.traces.sampler.arg define a taxa.
• 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.
• jaeger_remote configura JaegerRemoteSampler. otel.traces.sampler.arg é uma lista separada por vírgulas de argumentos como os descritos em especificações.

Propriedades para span limits:

Propriedades: métricas

Propriedades para periodic metric reader:

Propriedades para exemplars:

Propriedades para limites de cardinalidade:

Propriedades: logs

Propriedades para log record processor(s) pared with exporters via otel.logs.exporter:

Propriedades: exportadores

Propriedades para configurar exportadores:

[1]: Known exporters and artifacts (veja exportadores de trechos, exportadores de métricas, exportadores de registros for exporter artifact coordinates):

• 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 (essa opção é experimental e está sujeita a ser alterada ou removida).

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

Propriedades para otlp trecho, métrica, e exportadores de registros:

NOTE: The text placeholder {signal} refers to the supported OpenTelemetry Signal. Valid values include traces, metrics, and logs. Signal specific configurations take priority over the generic versions. Por exemplo, if you set both otel.exporter.otlp.endpoint and otel.exporter.otlp.traces.endpoint, the latter will take precedence.

[1]: OpenTelemetry Java agent 2.x and the OpenTelemetry Spring Boot starter use http/protobuf by default.

[2]: OTLP requer que erros transientes sejam tratados com uma estratégia de nova tentativa. Quando a opção de retry (nova tentativa) está habilitada, os códigos de status gRPC que permitem repetição serão novamente tentados usando um algoritmo de backoff exponencial com jitter. Essa opção específica do RetryPolicy só pode ser customizada via customizações programáticas.

Propriedades para zipkin exportadores de trechos:

Propriedades para prometheus exportadores de métricas.

Customizações programáticas

Customizações programáticas provê hooks para suplementar as propriedades suportadas com configurações programática.

Se estiver usando Spring starter, veja também spring starter configuração programática.

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()
        // Optionally customize TextMapPropagator.
        .addPropagatorCustomizer((textMapPropagator, configProperties) -> textMapPropagator)
        // Optionally customize Resource.
        .addResourceCustomizer((resource, configProperties) -> resource)
        // Optionally customize Sampler.
        .addSamplerCustomizer((sampler, configProperties) -> sampler)
        // Optionally customize SpanExporter.
        .addSpanExporterCustomizer((spanExporter, configProperties) -> spanExporter)
        // Optionally customize SpanProcessor.
        .addSpanProcessorCustomizer((spanProcessor, configProperties) -> spanProcessor)
        // Optionally supply additional properties.
        .addPropertiesSupplier(Collections::emptyMap)
        // Optionally customize ConfigProperties.
        .addPropertiesCustomizer(configProperties -> Collections.emptyMap())
        // Optionally customize SdkTracerProviderBuilder.
        .addTracerProviderCustomizer((builder, configProperties) -> builder)
        // Optionally customize SdkMeterProviderBuilder.
        .addMeterProviderCustomizer((builder, configProperties) -> builder)
        // Optionally customize MetricExporter.
        .addMetricExporterCustomizer((metricExporter, configProperties) -> metricExporter)
        // Optionally customize MetricReader.
        .addMetricReaderCustomizer((metricReader, configProperties) -> metricReader)
        // Optionally customize SdkLoggerProviderBuilder.
        .addLoggerProviderCustomizer((builder, configProperties) -> builder)
        // Optionally customize LogRecordExporter.
        .addLogRecordExporterCustomizer((logRecordExporter, configProperties) -> logRecordExporter)
        // Optionally customize LogRecordProcessor.
        .addLogRecordProcessorCustomizer((processor, configProperties) -> processor)
        .build()
        .getOpenTelemetrySdk();
  }
}

SPI (Service provider interface)

SPIs (artefato io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi:1.51.0) estendem a autoconfiguração do SDK além dos componentes já incluídos no SDK.

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

• Uma breve descrição, incluindo link para a referência do tipo Javadoc.
• Uma tabela com as implementações já incluídas e as do opentelemetry-java-contrib.
• Uma demonstração simples de uma implementação personalizada.

Provedor de Recursos

ResourceProviders contribute to the autoconfigured resource.

ResourceProviders built-in to the SDK and maintained by the community in opentelemetry-java-contrib:

Implementa a interface do ResourceProvider para participar no recurso de auto configuração. 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 invoked to contribute to the resource.
    return Resource.builder().put("my.custom.resource.attribute", "abc123").build();
  }

  @Override
  public int order() {
    // Optionally influence the order of invocation.
    return 0;
  }
}

AutoConfigurationCustomizerProvider

Implementa a interface AutoConfigurationCustomizerProvider para customizar uma variedade de componentes do SDK auto configurados. 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) {
    // Optionally customize TextMapPropagator.
    customizer.addPropagatorCustomizer((textMapPropagator, configProperties) -> textMapPropagator);
    // Optionally customize Resource.
    customizer.addResourceCustomizer((resource, configProperties) -> resource);
    // Optionally customize Sampler.
    customizer.addSamplerCustomizer((sampler, configProperties) -> sampler);
    // Optionally customize SpanExporter.
    customizer.addSpanExporterCustomizer((spanExporter, configProperties) -> spanExporter);
    // Optionally customize SpanProcessor.
    customizer.addSpanProcessorCustomizer((spanProcessor, configProperties) -> spanProcessor);
    // Optionally supply additional properties.
    customizer.addPropertiesSupplier(Collections::emptyMap);
    // Optionally customize ConfigProperties.
    customizer.addPropertiesCustomizer(configProperties -> Collections.emptyMap());
    // Optionally customize SdkTracerProviderBuilder.
    customizer.addTracerProviderCustomizer((builder, configProperties) -> builder);
    // Optionally customize SdkMeterProviderBuilder.
    customizer.addMeterProviderCustomizer((builder, configProperties) -> builder);
    // Optionally customize MetricExporter.
    customizer.addMetricExporterCustomizer((metricExporter, configProperties) -> metricExporter);
    // Optionally customize MetricReader.
    customizer.addMetricReaderCustomizer((metricReader, configProperties) -> metricReader);
    // Optionally customize SdkLoggerProviderBuilder.
    customizer.addLoggerProviderCustomizer((builder, configProperties) -> builder);
    // Optionally customize LogRecordExporter.
    customizer.addLogRecordExporterCustomizer((exporter, configProperties) -> exporter);
    // Optionally customize LogRecordProcessor.
    customizer.addLogRecordProcessorCustomizer((processor, configProperties) -> processor);
  }

  @Override
  public int order() {
    // Optionally influence the order of invocation.
    return 0;
  }
}

ConfigurableSpanExporterProvider

Implement the ConfigurableSpanExporterProvider interface to allow a custom exportadores de trechos to participate in autoconfiguration. 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 invoked when OTEL_TRACES_EXPORTER includes the value from getName().
    return new CustomSpanExporter();
  }

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

ConfigurableMetricExporterProvider

Implement the ConfigurableMetricExporterProvider interface to allow a custom exportadores de métricas to participate in autoconfiguration. 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 invoked when OTEL_METRICS_EXPORTER includes the value from getName().
    return new CustomMetricExporter();
  }

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

ConfigurableLogRecordExporterProvider

Implement the ConfigurableLogRecordExporterProvider interface to allow a custom log record exporter to participate in autoconfiguration. 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 invoked when OTEL_LOGS_EXPORTER includes the value from getName().
    return new CustomLogRecordExporter();
  }

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

ConfigurableSamplerProvider

Implement the ConfigurableSamplerProvider interface to allow a custom sampler to participate in autoconfiguration. For example:

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 invoked when OTEL_TRACES_SAMPLER is set to the value from getName().
    return new CustomSampler();
  }

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

ConfigurablePropagatorProvider

Implement the ConfigurablePropagatorProvider interface to allow a custom propagator to participate in autoconfiguration. For example:

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 invoked when OTEL_PROPAGATORS includes the value from getName().
    return new CustomTextMapPropagator();
  }

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

Configurações declarativas

Configurações declarativas estão em desenvolvimento atualmente. Elas permitem a configuração baseada em arquivos YAML, conforme descrito em configuração do OpenTelemetry e Configurações declarativas.

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

Para detalhes adicionais, consulte os links abaixo:

• Uso da Documentação
• Exemplo com Java agent
• Exemplo sem Java agent