DocsICP FilingConsole
官方文档
首页

OpenTelemetry integration guide

更新时间：
复制 MD 格式
产品详情
我的收藏

Managed Service for OpenTelemetry receives trace, metric, and log data from applications and offers two reporting methods: direct reporting and forwarding through the OpenTelemetry Collector.

Preparations

  • To report log data, you must first activate Simple Log Service (SLS), create a Project and a Logstore, and create an AccessKey pair for reporting log data.

  • Obtain the endpoint and authentication information. The following table lists the configuration variables described in this topic. Prepare the required information based on your scenario, such as the type of data to report and the reporting method. For more information, see Prerequisites.

    Scenario

    Variable name

    Description

    Example

    Report trace and metric data

    Report data over gRPC

    ${GRPC_ENDPOINT}

    The gRPC reporting endpoint of Managed Service for OpenTelemetry, which supports reporting Traces and Metrics data.

    If your service is deployed on Alibaba Cloud and in the same region as the selected endpoint, use an internal network address. Otherwise, use a public network address.

    • Internal network address: http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090

    • Public network address: http://tracing-analysis-dc-hz.aliyuncs.com:8090

    ${GRPC_AUTHENTICATION_TOKEN}

    The authentication token that is required when you use gRPC to report data to Managed Service for OpenTelemetry. For information about how to obtain the token, see Preparations.

    abcdef1234@abcdef****56789_abcdef1234@abcdef****56789

    Report data over HTTP

    ${HTTP_TRACES_ENDPOINT}

    The HTTP reporting endpoint of Managed Service for OpenTelemetry, which supports reporting trace data.

    If your service is deployed on Alibaba Cloud and in the same region as the selected endpoint, use an internal network address. Otherwise, use a public network address.

    • Internal network address: http://tracing-analysis-dc-hz-internal.aliyuncs.com/adapt_***_***/api/otlp/traces

    • Public network address: http://tracing-analysis-dc-hz.aliyuncs.com/adapt_***_***/api/otlp/traces

    ${HTTP_METRICS_ENDPOINT}

    The HTTP reporting endpoint for Managed Service for OpenTelemetry supports reporting metric data.

    If your service is deployed on Alibaba Cloud and in the same region as the selected endpoint, use an internal network address. Otherwise, use a public network address.

    • Internal network address: http://tracing-analysis-dc-hz-internal.aliyuncs.com/adapt_***_***/api/otlp/metrics

    • Public network address: http://tracing-analysis-dc-hz.aliyuncs.com/adapt_***_***/api/otlp/metrics

    Report log data

    ${SLS_ENDPOINT}

    The endpoint of the SLS project. This variable is required only when you report log data. For information about how to obtain the endpoint, see Endpoints.

    test-project.cn-hangzhou.log.aliyuncs.com

    ${SLS_PROJECT}

    The name of the SLS project. This variable is required only when you report log data.

    test-project

    ${SLS_LOGSTORE}

    The name of the SLS Logstore. This variable is required only when you report log data.

    test-logstore

    ${ALIYUN_ACCESS_KEY_ID}

    The AccessKey ID of your Alibaba Cloud account. This variable is required only when you report log data.

    We recommend that you use the AccessKey pair of a Resource Access Management (RAM) user that has only the write permissions on the Simple Log Service project. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. For information about how to grant a RAM user the permissions to write data to a specified project, see Examples of custom RAM policies. For information about how to obtain an AccessKey pair, see AccessKey pair.

    None

    ${ALIYUN_ACCESS_KEY_SECRET}

    The AccessKey secret of your Alibaba Cloud account. This variable is required only when you report log data.

    Use the AccessKey pair of a RAM user that has only the write permissions on the SLS project.

    None

Direct reporting

You can configure the reporting endpoint and authentication token of the OpenTelemetry Agent or SDK to send trace and metric data directly to the Managed Service for OpenTelemetry server.

Method 1: Configure reporting information in code (Java example)

The following Java code example shows how to configure the endpoint for Managed Service for OpenTelemetry to report data over HTTP or gRPC. For the complete code and demo, visit the Integration Center or see Use OpenTelemetry to report the trace data of Java applications.

Report data over HTTP

...

// Report trace data
SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
        .addSpanProcessor(BatchSpanProcessor.builder(OtlpHttpSpanExporter.builder()
                .setEndpoint("${HTTP_TRACES_ENDPOINT}") // Set the HTTP endpoint for traces to report trace data to Managed Service for OpenTelemetry.
                .build()).build())
        .build();

// Report metric data
SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
    .registerMetricReader(PeriodicMetricReader.builder(OtlpHttpMetricExporter.builder()
        .setEndpoint("${HTTP_METRICS_ENDPOINT}")  // Set the HTTP endpoint for metrics to report metric data to Managed Service for OpenTelemetry.
        .build()).build())
    .build();

...

Report data over gRPC

...

// Report trace data
SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
        .addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder()
                .setEndpoint("${GRPC_AUTHENTICATION_TOKEN}") // Set the gRPC endpoint to report trace data to Managed Service for OpenTelemetry.
                .addHeader("Authentication","${GRPC_AUTHENTICATION_TOKEN}") // Set the authentication token for Managed Service for OpenTelemetry.
                .build()).build())
        .setResource(resource)
        .build();

// Report metric data
SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
    .registerMetricReader(PeriodicMetricReader.builder(OtlpGrpcMetricExporter.builder()
        .setEndpoint("${GRPC_METRICS_ENDPOINT}")  // Set the gRPC endpoint to report trace data to Managed Service for OpenTelemetry.
        .addHeader("Authentication", "${GRPC_AUTHENTICATION_TOKEN}")  // Set the authentication token for Managed Service for OpenTelemetry.
        .build()).build())
    .setResource(resource)
    .build();

...

Method 2: Set reporting information using environment variables

OpenTelemetry also lets you configure the data reporting endpoint using environment variables. The following table lists the environment variables required to report data to Managed Service for OpenTelemetry. For more information about OpenTelemetry OTLP environment variables, see OTLP Exporter Configuration.

Environment variable name

Description

Example

OTEL_SERVICE_NAME

The application name.

export OTEL_SERVICE_NAME=opentelemetry-demo-service

OTEL_EXPORTER_OTLP_PROTOCOL

The reporting protocol.

Traces support grpc, http/protobuf, and http/json.

Metrics support grpc and http/protobuf.

If you select a gRPC endpoint, set this variable to grpc. Otherwise, use http/protobuf or http/json.

export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT

The endpoint for reporting traces. HTTP and gRPC endpoints are supported.

The reporting endpoint is the value of ${GRPC_ENDPOINT} or ${HTTP_TRACES_ENDPOINT} obtained in Prerequisites.

  • HTTP reporting:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://tracing-analysis-dc-hz-internal.aliyuncs.com/adapt_***_***/api/otlp/traces

  • gRPC reporting:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090

OTEL_EXPORTER_OTLP_METRICS_ENDPOINT

The endpoint for reporting metrics. HTTP and gRPC endpoints are supported.

The reporting endpoint is the value of ${GRPC_ENDPOINT} or ${HTTP_METRICS_ENDPOINT} obtained in Prerequisites.

  • HTTP reporting:

export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://tracing-analysis-dc-hz-internal.aliyuncs.com/adapt_***_***/api/otlp/metrics

  • gRPC reporting:

export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090

OTEL_EXPORTER_OTLP_HEADERS

The request header information for gRPC reporting. This is mainly used for identity verification.

The format is Authentication=${GRPC_AUTHENTICATION_TOKEN}, where ${GRPC_AUTHENTICATION_TOKEN} is the authentication token obtained in Prerequisites.

export OTEL_EXPORTER_OTLP_HEADERS=Authentication=abcdef1234@abcdef****56789_abcdef1234@abcdef****56789

Forward data using an OpenTelemetry Collector

Version guide

  • OpenTelemetry Collector (Core): reports trace and metric data.

  • OpenTelemetry Collector Contrib: reports trace, metric, and log data.

Deployment method 1: One-click deployment to an ACK cluster from the ACK Marketplace

Important

The ACK Marketplace currently supports only the Core edition of the OpenTelemetry Collector. The Contrib edition is not available. To collect logs, you must use another deployment method.

1. Deploy the Collector

  1. Log on to the ACK console. In the left navigation pane, choose Marketplace > Marketplace.

  2. In the Marketplace, search for opentelemetry-collector and select it, then click One-click Deploy in the upper-right corner of the page.

  3. On the Create page, select the cluster and namespace (default: otel-collector) to deploy opentelemetry-collector, and then click Next.

  4. On the Parameters page, set the mode parameter to deployment or daemonset, and click OK.

2. Configure Collector parameters

  1. On the Clusters page, click the target cluster.

  2. In the navigation pane on the left, choose Configurations > ConfigMaps.

  3. Select the namespace where the opentelemetry-collector is located. The default namespace is otel-collector.

  4. On the ConfigMap page, find opentelemetry-collector and click Edit YAML.

  5. Configure the exporters, processors, receivers, and service sections based on the following YAML, and then click OK.

    opentelemetry-collector configuration (gRPC reporting)

    exporters:
  otlp:
    endpoint: "${GRPC_ENDPOINT}"
    headers:
      Authentication: "${GRPC_AUTHENTICATION_TOKEN}"
    tls:
      insecure: true

processors:
  batch: {}
  memory_limiter:
    check_interval: 5s # The interval at which to check memory usage. Change the value as needed.
    limit_percentage: 80 # The maximum percentage of memory that can be used. Change the value as needed.
    spike_limit_percentage: 25 # The percentage of additional memory that is allowed for bursts. Change the value as needed.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:4317
      http:
        endpoint: ${env:MY_POD_IP}:4318

service:
  pipelines:
    traces:
      exporters: [otlp]
      processors: [memory_limiter, batch]
      receivers: [otlp]
    metrics:
      exporters: [otlp]
      processors: [memory_limiter, batch]
      receivers: [otlp]

    opentelemetry-collector configuration (HTTP reporting)

    exporters:
  otlphttp:
    traces_endpoint: "${HTTP_TRACES_ENDPOINT}"
    metrics_endpoint: "${HTTP_METRICS_ENDPOINT}"
    tls:
      insecure: true
    timeout: 5s # The timeout period. The default is 5s. Change the value as needed.

processors:
  batch: {}
  memory_limiter:
    check_interval: 5s # The interval at which to check memory usage. Change the value as needed.
    limit_percentage: 80 # The maximum percentage of memory that can be used. Change the value as needed.
    spike_limit_percentage: 25 # The percentage of additional memory that is allowed for bursts. Change the value as needed.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:4317
      http:
        endpoint: ${env:MY_POD_IP}:4318

service:
  pipelines:
    traces:
      exporters: [otlphttp]
      processors: [memory_limiter, batch]
      receivers: [otlp]
    metrics:
      exporters: [otlphttp]
      processors: [memory_limiter, batch]
      receivers: [otlp]

  6. After the configuration is complete, manually restart the opentelemetry-collector.

Deployment method 2: Deploy using Docker

1. Pull an image

opentelemetry-collector

To specify an image version, visit https://hub.docker.com/r/otel/opentelemetry-collector/tags.

docker pull otel/opentelemetry-collector:latest

opentelemetry-collector-contrib

To specify an image version, visit https://hub.docker.com/r/otel/opentelemetry-collector-contrib/tags.

docker pull otel/opentelemetry-collector-contrib:latest
2. Prepare a configuration file

Create a config.yaml file and configure the parameters.

opentelemetry-collector configuration (gRPC reporting)

# config.yaml
exporters:
  otlp:
    endpoint: "${GRPC_ENDPOINT}"
    headers:
      Authentication: "${GRPC_AUTHENTICATION_TOKEN}"
    tls:
      insecure: true

processors:
  batch: {}
  memory_limiter:
    check_interval: 5s # The interval at which to check memory usage. Change the value as needed.
    limit_percentage: 80 # The maximum percentage of memory that can be used. Change the value as needed.
    spike_limit_percentage: 25 # The percentage of additional memory that is allowed for bursts. Change the value as needed.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317 # The default is localhost:4317. Change the value as needed.
      http:
        endpoint: 0.0.0.0:4318 # The default is localhost:4318. Change the value as needed.

service:
  pipelines:
    traces:
      exporters: [otlp]
      processors: [memory_limiter, batch]
      receivers: [otlp]
    metrics:
      exporters: [otlp]
      processors: [memory_limiter, batch]
      receivers: [otlp]

opentelemetry-collector configuration (HTTP reporting)

# config.yaml
exporters:
  otlphttp:
    traces_endpoint: "${HTTP_TRACES_ENDPOINT}"
    metrics_endpoint: "${HTTP_METRICS_ENDPOINT}"
    tls:
      insecure: true
    timeout: 5s # The timeout period. The default is 5s. Change the value as needed.

processors:
  batch: {}
  memory_limiter:
    check_interval: 5s # The interval at which to check memory usage. Change the value as needed.
    limit_percentage: 80 # The maximum percentage of memory that can be used. Change the value as needed.
    spike_limit_percentage: 25 # The percentage of additional memory that is allowed for bursts. Change the value as needed.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317 # The default is localhost:4317. Change the value as needed.
      http:
        endpoint: 0.0.0.0:4318 # The default is localhost:4318. Change the value as needed.

service:
  pipelines:
    traces:
      exporters: [otlphttp]
      processors: [memory_limiter, batch]
      receivers: [otlp]
    metrics:
      exporters: [otlphttp]
      processors: [memory_limiter, batch]
      receivers: [otlp]

opentelemetry-collector-contrib configuration (gRPC reporting)

# config.yaml
exporters:
  otlp:
    endpoint: "${GRPC_ENDPOINT}"
    headers:
      Authentication: "${GRPC_AUTHENTICATION_TOKEN}"
    tls:
      insecure: true
  # (Optional) Log exporter configuration
  alibabacloud_logservice/logs:
    endpoint: "${SLS_ENDPOINT}"
    project: "${SLS_PROJECT}"
    logstore: "${SLS_LOGSTORE}"
    access_key_id: "${ALIYUN_ACCESS_KEY_ID}"
    access_key_secret: "${ALIYUN_ACCESS_KEY_SECRET}"

processors:
  batch: {}
  memory_limiter:
    check_interval: 5s # The interval at which to check memory usage. Change the value as needed.
    limit_percentage: 80 # The maximum percentage of memory that can be used. Change the value as needed.
    spike_limit_percentage: 25 # The percentage of additional memory that is allowed for bursts. Change the value as needed.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317 # The default is localhost:4317. Change the value as needed.
      http:
        endpoint: 0.0.0.0:4318 # The default is localhost:4318. Change the value as needed.

service:
  pipelines:
    traces:
      exporters: [otlp]
      processors: [memory_limiter, batch]
      receivers: [otlp]
    metrics:
      exporters: [otlp]
      processors: [memory_limiter, batch]
      receivers: [otlp]
    # (Optional) Log data processing pipeline
    logs:
      exporters: [alibabacloud_logservice/logs]
      processors: [memory_limiter, batch]
      receivers: [otlp]

opentelemetry-collector-contrib configuration (HTTP reporting)

# config.yaml
exporters:
  otlphttp:
    traces_endpoint: "${HTTP_TRACES_ENDPOINT}"
    metrics_endpoint: "${HTTP_METRICS_ENDPOINT}"
    tls:
      insecure: true
    timeout: 5s # The timeout period. The default is 5s. Change the value as needed.
    
  # (Optional) Log exporter configuration
  alibabacloud_logservice/logs:
    endpoint: "${SLS_ENDPOINT}"
    project: "${SLS_PROJECT}"
    logstore: "${SLS_LOGSTORE}"
    access_key_id: "${ALIYUN_ACCESS_KEY_ID}"
    access_key_secret: "${ALIYUN_ACCESS_KEY_SECRET}"

processors:
  batch: {}
  memory_limiter:
    check_interval: 5s # The interval at which to check memory usage. Change the value as needed.
    limit_percentage: 80 # The maximum percentage of memory that can be used. Change the value as needed.
    spike_limit_percentage: 25 # The percentage of additional memory that is allowed for bursts. Change the value as needed.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317 # The default is localhost:4317. Change the value as needed.
      http:
        endpoint: 0.0.0.0:4318 # The default is localhost:4318. Change the value as needed.

service:
  pipelines:
    traces:
      exporters: [otlphttp]
      processors: [memory_limiter, batch]
      receivers: [otlp]
    metrics:
      exporters: [otlphttp]
      processors: [memory_limiter, batch]
      receivers: [otlp]
    # (Optional) Log data processing pipeline
    logs:
      exporters: [alibabacloud_logservice/logs]
      processors: [memory_limiter, batch]
      receivers: [otlp]
3. Mount the custom configuration file and run the container

opentelemetry-collector

docker run -v $(pwd)/config.yaml:/etc/otelcol/config.yaml otel/opentelemetry-collector:latest

opentelemetry-collector-contrib

docker run -v $(pwd)/config.yaml:/etc/otelcol-contrib/config.yaml otel/opentelemetry-collector-contrib:latest

Other installation and deployment methods

References

Previous：Integrate services or componentsNext：Get started with Managed Service for OpenTelemetry