Налаштування SDK

SDK є вбудованою референсною реалізацією API, яка обробляє та експортує телеметрію, створену викликами API інструментування. Налаштування SDK для належної обробки та експорту є важливим кроком для інтеграції OpenTelemetry в застосунок.

Усі компоненти SDK мають програмні інтерфейси налаштування. Це найгнучкіший і найвиразніший спосіб налаштування SDK. Однак зміна налаштувань вимагає коригування коду та перекомпіляції застосунку, і немає міжмовної сумісності, оскільки API написано на Java.

Модуль автоконфігурації SDK без коду налаштовує компоненти SDK через системні властивості або змінні середовища з різними точками розширення для випадків, коли властивостей недостатньо.

Програмне налаштування

Інтерфейс програмного налаштування — це набір API для створення компонентів SDK. Усі компоненти SDK мають програмний інтерфейс налаштування, і всі інші механізми налаштування побудовані на основі цього API. Наприклад, інтерфейс налаштування змінних середовища та системних властивостей інтерпретує відомі змінні середовища та системні властивості в серію викликів до програмного інтерфейсу налаштування.

Хоча інші механізми налаштування пропонують більше зручності, жоден з них не пропонує такої гнучкості, як написання коду, що виражає точні налаштування. Коли певна можливість не підтримується механізмом налаштування вищого рівня, у вас може не залишитися іншого вибору, окрім як використовувати програмне налаштування.

Розділи компонентів SDK демонструють простий програмний інтерфейс налаштування для ключових областей SDK, з якими стикаються користувачі. Зверніться до коду для повної довідки по API.

Автоконфігурація SDK без коду

Модуль автоконфігурації (артефакт io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.59.0) є інтерфейсом налаштування, побудованим на основі інтерфейсу програмного налаштування, який налаштовує компоненти SDK без коду. Існує два різних робочих процеси автоконфігурації:

• Змінні середовища та системні властивості інтерпретують змінні середовища та системні властивості для створення компонентів SDK, включаючи різні точки налаштування для накладання програмного налаштування.
• Декларативне налаштування (наразі в розробці) інтерпретує модель налаштування для створення компонентів SDK, яка зазвичай кодується у YAML файлі налаштування.

Автоматично налаштуйте компоненти SDK за допомогою автоконфігурації наступним чином:

package otel;

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

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

Змінні середовища та системні властивості

Модуль автоконфігурації підтримує властивості, перелічені в специфікації налаштування змінних середовища, з періодичними експериментальними та специфічними для Java доповненнями.

Наступні властивості перелічені як системні властивості, але також можуть бути встановлені за допомогою змінних середовища. Виконайте наступні кроки, щоб перетворити системну властивість на змінну середовища:

• Перетворіть імʼя на великі літери.
• Замініть усі символи . та - на _.

Наприклад, системна властивість otel.sdk.disabled еквівалентна змінній середовища OTEL_SDK_DISABLED.

Якщо властивість визначена як системна властивість і змінна середовища, пріоритет має системна властивість.

Властивості: загальні

Властивості для відключення SDK:

[1]: Якщо відключено, AutoConfiguredOpenTelemetrySdk#getOpenTelemetrySdk() повертає мінімально налаштований екземпляр (наприклад, OpenTelemetrySdk.builder().build()).

Властивості для обмежень атрибутів (див. обмеження відрізків, обмеження логів):

Властивості для поширення контексту:

[1]: Відомі поширювачі та артефакти (див. text map propagator для координат артефакту):

• tracecontext налаштовує W3CTraceContextPropagator.
• baggage налаштовує W3CBaggagePropagator.
• b3, b3multi налаштовує B3Propagator.
• jaeger налаштовує JaegerPropagator.
• ottrace налаштовує OtTracePropagator.
• xray налаштовує AwsXrayPropagator.
• xray-lambda налаштовує AwsXrayLambdaPropagator.

Властивості: ресурс

Властивості для налаштування ресурсу:

[1]: Наприклад, щоб відключити провайдера ресурсу ОС, встановіть -Dotel.java.disabled.resource.providers=io.opentelemetry.instrumentation.resources.OsResourceProvider. Дивіться ResourceProvider для координат артефакту провайдера ресурсів.

ПРИМІТКА: Системні властивості/змінні оточення otel.service.name та otel.resource.attributes інтерпретуються у постачальнику ресурсів io.opentelemetry.sdk.autoconfigure.EnvironmentResourceProvider. Якщо ви вирішили вказати постачальників ресурсів за допомогою otel.java.enabled.resource-providers, ви, ймовірно, захочете включити цей параметр, щоб уникнути несподіванок. Координати артефакту постачальника ресурсів наведено у ResourceProvider.

Властивості: трейсинг

Властивості для пакетного процесора відрізків, повʼязаного з експортерами, зазначеними через otel.traces.exporter:

Властивості для семплера:

[1]: Відомі семплери та артефакти (див. sampler для координат артефакту):

• always_on налаштовує AlwaysOnSampler.
• always_off налаштовує AlwaysOffSampler.
• traceidratio налаштовує TraceIdRatioBased. otel.traces.sampler.arg встановлює коефіцієнт.
• parentbased_always_on налаштовує ParentBased(root=AlwaysOnSampler).
• parentbased_always_off налаштовує ParentBased(root=AlwaysOffSampler).
• parentbased_traceidratio налаштовує ParentBased(root=TraceIdRatioBased). otel.traces.sampler.arg встановлює коефіцієнт.
• jaeger_remote налаштовує JaegerRemoteSampler. otel.traces.sampler.arg є списком аргументів через кому, як описано в специфікації.

Властивості для обмежень відрізків:

Властивості: метрики

Властивості для періодичного читача метрик:

Властивості для екземплярів:

Властивості для обмежень кардинальності:

Властивості: логи

Властивості для процесора записів логів, повʼязаного з експортерами через otel.logs.exporter:

Властивості: експортери

Властивості для налаштування експортерів:

[1]: Відомі експортери та артефакти (див. span exporter, metric exporter, log exporter для координат артефакту експортера):

• otlp налаштовує OtlpHttp{Signal}Exporter / OtlpGrpc{Signal}Exporter.
• zipkin налаштовує ZipkinSpanExporter.
• console налаштовує LoggingSpanExporter, LoggingMetricExporter, SystemOutLogRecordExporter.
• logging-otlp налаштовує OtlpJsonLogging{Signal}Exporter.
• experimental-otlp/stdout налаштовує OtlpStdout{Signal}Exporter (ця опція є експериментальною і може бути змінена або видалена).

[2]: Експортери, які дотримуються otel.java.exporter.memory_mode=reusable_data включають OtlpGrpc{Signal}Exporter, OtlpHttp{Signal}Exporter, OtlpStdout{Signal}Exporter, та PrometheusHttpServer.

Властивості для otlp експортерів відрізків, метрик та логів:

ПРИМІТКА: Текстовий заповнювач {signal} відноситься до підтримуваного OpenTelemetry Signal. Дійсні значення включають traces, metrics, та logs. Конфігурації, специфічні для сигналу, мають пріоритет над загальними версіями. Наприклад, якщо ви встановите як otel.exporter.otlp.endpoint, так і otel.exporter.otlp.traces.endpoint, останній матиме пріоритет.

[1]: OpenTelemetry Java агент 2.x та OpenTelemetry Spring Boot starter використовують стандартно http/protobuf.

[2]: OTLP вимагає щоб тимчасові помилки оброблялись зі стратегією повторної спроби. Коли повторна спроба увімкнена, повторювані коди стану gRPC повторюються використовуючи алгоритм експоненційного зворотного відліку з джитером. Конкретні опції RetryPolicy можна налаштувати лише через програмну налаштування.

Властивості для zipkin експортера відрізків:

Властивості для prometheus експортера метрик.

Програмне налаштування

Програмне налаштування надає хуки для доповнення підтримуваних властивостей з програмним налаштуванням.

Якщо ви використовуєте Spring starter, дивіться також spring starter програмне налаштування.

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()
        // Опціонально налаштуйте TextMapPropagator.
        .addPropagatorCustomizer((textMapPropagator, configProperties) -> textMapPropagator)
        // Опціонально налаштуйте Resource.
        .addResourceCustomizer((resource, configProperties) -> resource)
        // Опціонально налаштуйте Sampler.
        .addSamplerCustomizer((sampler, configProperties) -> sampler)
        // Опціонально налаштуйте SpanExporter.
        .addSpanExporterCustomizer((spanExporter, configProperties) -> spanExporter)
        // Опціонально налаштуйте SpanProcessor.
        .addSpanProcessorCustomizer((spanProcessor, configProperties) -> spanProcessor)
        // Опціонально надайте додаткові властивості.
        .addPropertiesSupplier(Collections::emptyMap)
        // Опціонально налаштуйте ConfigProperties.
        .addPropertiesCustomizer(configProperties -> Collections.emptyMap())
        // Опціонально налаштуйте SdkTracerProviderBuilder.
        .addTracerProviderCustomizer((builder, configProperties) -> builder)
        // Опціонально налаштуйте SdkMeterProviderBuilder.
        .addMeterProviderCustomizer((builder, configProperties) -> builder)
        // Опціонально налаштуйте MetricExporter.
        .addMetricExporterCustomizer((metricExporter, configProperties) -> metricExporter)
        // Опціонально налаштуйте MetricReader.
        .addMetricReaderCustomizer((metricReader, configProperties) -> metricReader)
        // Опціонально налаштуйте SdkLoggerProviderBuilder.
        .addLoggerProviderCustomizer((builder, configProperties) -> builder)
        // Опціонально налаштуйте LogRecordExporter.
        .addLogRecordExporterCustomizer((logRecordExporter, configProperties) -> logRecordExporter)
        // Опціонально налаштуйте LogRecordProcessor.
        .addLogRecordProcessorCustomizer((processor, configProperties) -> processor)
        .build()
        .getOpenTelemetrySdk();
  }
}

SPI (Service provider interface)

SPIs (артефакт io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi:1.59.0) розширюють автоконфігурацію SDK за межі компонентів, вбудованих у SDK.

Наступні розділи описують доступні SPIs. Кожен розділ SPI включає:

• Короткий опис, включаючи посилання на тип довідки Javadoc.
• Таблицю доступних вбудованих та opentelemetry-java-contrib реалізацій.
• Просту демонстрацію користувацької реалізації.

ResourceProvider

ResourceProvider додають до автоконфігурованого ресурсу.

ResourceProvider, вбудовані в SDK та підтримувані спільнотою в opentelemetry-java-contrib:

Реалізуйте інтерфейс ResourceProvider, щоб брати участь у автоконфігурації ресурсів. Наприклад:

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) {
    // Виклик зворотного виклику для додавання до ресурсу.
    return Resource.builder().put("my.custom.resource.attribute", "abc123").build();
  }

  @Override
  public int order() {
    // Опціонально впливайте на порядок викликів.
    return 0;
  }
}

AutoConfigurationCustomizerProvider

Реалізуйте інтерфейс AutoConfigurationCustomizerProvider для налаштування різних автоконфігурованих компонентів SDK. Наприклад:

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) {
    // Опціонально налаштуйте TextMapPropagator.
    customizer.addPropagatorCustomizer((textMapPropagator, configProperties) -> textMapPropagator);
    // Опціонально налаштуйте Resource.
    customizer.addResourceCustomizer((resource, configProperties) -> resource);
    // Опціонально налаштуйте Sampler.
    customizer.addSamplerCustomizer((sampler, configProperties) -> sampler);
    // Опціонально налаштуйте SpanExporter.
    customizer.addSpanExporterCustomizer((spanExporter, configProperties) -> spanExporter);
    // Опціонально налаштуйте SpanProcessor.
    customizer.addSpanProcessorCustomizer((spanProcessor, configProperties) -> spanProcessor);
    // Опціонально надайте додаткові властивості.
    customizer.addPropertiesSupplier(Collections::emptyMap);
    // Опціонально налаштуйте ConfigProperties.
    customizer.addPropertiesCustomizer(configProperties -> Collections.emptyMap());
    // Опціонально налаштуйте SdkTracerProviderBuilder.
    customizer.addTracerProviderCustomizer((builder, configProperties) -> builder);
    // Опціонально налаштуйте SdkMeterProviderBuilder.
    customizer.addMeterProviderCustomizer((builder, configProperties) -> builder);
    // Опціонально налаштуйте MetricExporter.
    customizer.addMetricExporterCustomizer((metricExporter, configProperties) -> metricExporter);
    // Опціонально налаштуйте MetricReader.
    customizer.addMetricReaderCustomizer((metricReader, configProperties) -> metricReader);
    // Опціонально налаштуйте SdkLoggerProviderBuilder.
    customizer.addLoggerProviderCustomizer((builder, configProperties) -> builder);
    // Опціонально налаштуйте LogRecordExporter.
    customizer.addLogRecordExporterCustomizer((exporter, configProperties) -> exporter);
    // Опціонально налаштуйте LogRecordProcessor.
    customizer.addLogRecordProcessorCustomizer((processor, configProperties) -> processor);
  }

  @Override
  public int order() {
    // Опціонально впливайте на порядок викликів.
    return 0;
  }
}

ConfigurableSpanExporterProvider

Реалізуйте інтерфейс ConfigurableSpanExporterProvider для дозволу користувацького експортера відрізків брати участь у автоконфігурації. Наприклад:

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) {
    // Виклик зворотного виклику, коли OTEL_TRACES_EXPORTER включає значення з getName().
    return new CustomSpanExporter();
  }

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

ConfigurableMetricExporterProvider

Реалізуйте інтерфейс ConfigurableMetricExporterProvider для дозволу користувацького експортера метрик брати участь у автоконфігурації. Наприклад:

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) {
    // Виклик зворотного виклику, коли OTEL_METRICS_EXPORTER включає значення з getName().
    return new CustomMetricExporter();
  }

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

ConfigurableLogRecordExporterProvider

Реалізуйте інтерфейс ConfigurableLogRecordExporterProvider для дозволу користувацького експортера записів логів брати участь у автоконфігурації. Наприклад:

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) {
    // Виклик зворотного виклику, коли OTEL_LOGS_EXPORTER включає значення з getName().
    return new CustomLogRecordExporter();
  }

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

ConfigurableSamplerProvider

Реалізуйте інтерфейс ConfigurableSamplerProvider для дозволу користувацького семплера брати участь у автоконфігурації. Наприклад:

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) {
    // Виклик зворотного виклику, коли OTEL_TRACES_SAMPLER встановлено на значення з getName().
    return new CustomSampler();
  }

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

ConfigurablePropagatorProvider

Реалізуйте інтерфейс ConfigurablePropagatorProvider для дозволу користувацького поширювача брати участь у автоконфігурації. Наприклад:

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) {
    // Виклик зворотного виклику, коли OTEL_PROPAGATORS включає значення з getName().
    return new CustomTextMapPropagator();
  }

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

Декларативне налаштування

Декларативне налаштування наразі в розробці. Воно дозволяє налаштування на основі YAML файлу, як описано в opentelemetry-configuration та декларативне налаштування.

Для використання, включіть io.opentelemetry:opentelemetry-sdk-extension-incubator:1.59.0-alpha та вкажіть шлях до файлу налаштувань, як описано в таблиці нижче.

Для отримання додаткової інформації зверніться до наступних ресурсів:

• Документація з використання
• Приклад з Java агентом
• Приклад без Java агента