tencent cloud

Cloud Log Service

DokumentasiCloud Log ServiceOperation GuideLog CollectionIntegrating OpenTelemetry SDK with CLS

Integrating OpenTelemetry SDK with CLS

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-10-12 15:04:42
Diterjemahkan oleh AI

Scenarios

CLS is compatible with the OpenTelemetry OTLP/HTTP protocol. Developers can complete data reporting by simply using the standard OTLP Exporter and configuring the corresponding Endpoint, Authorization, and topic_id, without the need to introduce a CLS-specific SDK. This document describes how to report three types of observability data-Trace, Metric, and Log-to Tencent ClouCloud Log Service (CLS)ng the OpenTelemetry (OTLP) SDK in a Go project. The unified specifications for reporting these three data types are as follows:
Data Type
SDK Module
Exporter
Log
go.opentelemetry.io/otel/sdk/log
otlploghttp
Trace
go.opentelemetry.io/otel/sdk/trace
otlptracehttp
Metric
go.opentelemetry.io/otel/sdk/metric
otlpmetrichttp

Prerequisites

You have registered a Tencent Cloud account and activated CLS.
Create a logset and log topics in the target region and record the topic_id for each topic. For detailed operations, see Create Log Topic.
Obtain the SecretId (AK) and SecretKey (SK) of the sub-account. For detailed operations, see Access Key.
Note:
Avoid hardcoding AK/SK in code or committing them to a code repository. Instead, inject them via environment variables or a key management service.
Go version 1.21 or later is installed locally.

Operation Steps

Step 1: Determining the Reporting Endpoint

CLS provides two types of access points: public network and private network. Select one based on your network environment.
Network type
Domain Name Format
Scenario
Public Network
<region>.cls.tencentcs.com
Local debugging, non-Tencent Cloud environments, cross-cloud reporting
Private Network
<region>.cls.tencentyun.com
Deployed in Tencent Cloud VPCs/CVMs within the same region, with no public network traffic fees and low latency.
The mapping table for common region Endpoints is provided below.
Region
Public Endpoint
Private Endpoint
Guangzhou
ap-guangzhou.cls.tencentcs.com
ap-guangzhou.cls.tencentyun.com
Shanghai
ap-shanghai.cls.tencentcs.com
ap-shanghai.cls.tencentyun.com
Beijing
ap-beijing.cls.tencentcs.com
ap-beijing.cls.tencentyun.com
Singapore
ap-singapore.cls.tencentcs.com
ap-singapore.cls.tencentyun.com
Note:
Private network access points are accessible only within the Tencent Cloud private network of the same region. For cross-region or public network environments, use public network access points.

Step 2: Installing Dependencies

Run the following command in the project directory to install OpenTelemetry dependencies (use the latest stable version).
# OpenTelemetry Core
go get go.opentelemetry.io/otel
go get go.opentelemetry.io/otel/sdk

# Log
go get go.opentelemetry.io/otel/log
go get go.opentelemetry.io/otel/sdk/log
go get go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp

# Trace
go get go.opentelemetry.io/otel/sdk/trace
go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp

# Metric
go get go.opentelemetry.io/otel/sdk/metric
go get go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp

# Semantic Conventions
go get go.opentelemetry.io/otel/semconv/v1.37.0

Step 3: Implementing the Authentication Function

The CLS OTLP access point uses HTTP Basic authentication. The request header format is as follows.
Authorization: Basic base64(SecretId:SecretKey)
topic_id:      <Your topic_id>
Implement the authentication function in your Go project.
import "encoding/base64"

func basicAuth(username, password string) string {
    auth := username + ":" + password
    return base64.StdEncoding.EncodeToString([]byte(auth))
}

Step 4: Integrating Logs

Create an OTLP/HTTP Log Exporter and attach it to the LoggerProvider.
package main

import (
    "context"

    "go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp"
)

func otlplog() {
    ctx := context.Background()

    // Create an OTLP/HTTP Log Exporter
    exporter, err := otlploghttp.New(ctx,
        otlploghttp.WithEndpoint("ap-guangzhou.cls.tencentcs.com"),
        otlploghttp.WithHeaders(map[string]string{
            "Authorization": "Basic " + basicAuth("<SecretId>", "<SecretKey>"),
            "topic_id":      "<log topic_id>",
        }),
    )
    if err != nil {
        panic(err)
    }
    _ = exporter
    // Subsequently, you can upload logs by using sdklog.NewLoggerProvider(...) to attach the exporter to the LoggerProvider.
}
Key Parameter Description:
Parameter
Description
Endpoint
The CLS OTLP endpoint domain name. Do not include the http:// prefix.
Authorization
The authentication header in the Basic base64(AK:SK) format
topic_id
The CLS log topic ID corresponding to the log data
Processor Selection:
SimpleProcessor: It exports synchronously, uploading each log as it is written, making it suitable for debugging environments.
BatchProcessor (Recommended): It exports asynchronously in batches, reducing the upload frequency, making it suitable for production environments.
sdklog.WithProcessor(sdklog.NewBatchProcessor(exporter,
     sdklog.WithExportInterval(5*time.Second),
     sdklog.WithExportMaxBatchSize(512),
 ))

Step 5: Integrating Trace (Link Tracing)

Create an OTLP/HTTP Trace Exporter and attach it to the TracerProvider.
package main

import (
    "context"
    "log"

    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
)

func otlptrace() {
    ctx := context.Background()

    // Create an OTLP/HTTP Trace Exporter
    traceExporter, err := otlptracehttp.New(ctx,
        otlptracehttp.WithEndpoint("ap-guangzhou.cls.tencentcs.com"),
        otlptracehttp.WithHeaders(map[string]string{
            "Authorization": "Basic " + basicAuth("<SecretId>", "<SecretKey>"),
            "topic_id":      "<trace topic_id>",
        }),
    )
    if err != nil {
        log.Printf("create trace exporter failed: %v", err)
        return
    }
    _ = traceExporter
    // Subsequently, you can upload traces by using sdktrace.NewTracerProvider(...) to attach the exporter.
}
Sampler (Sampler) Selection:
Sampler
Description
AlwaysSample()
Samples all traffic, suitable for testing or low-traffic services.
NeverSample()
Samples no traffic.
TraceIDRatioBased(0.1)
Samples traffic at a ratio (10%), recommended for production.
ParentBased(...)
Decides based on the parent Span, suitable for distributed tracing scenarios.
SpanProcessor Configuration (BatchSpanProcessor Recommended for Production):
sdktrace.WithSpanProcessor(sdktrace.NewBatchSpanProcessor(traceExporter,
    sdktrace.WithMaxExportBatchSize(512),
    sdktrace.WithBatchTimeout(5*time.Second),
))

Step 6: Integrating Metric (Metrics)

Create an OTLP/HTTP Metric Exporter and attach it to the MeterProvider.
package main

import (
    "context"

    "go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp"
)

func otlpMetric() {
    ctx := context.Background()

    // Create an OTLP/HTTP Metric Exporter
    exporter, err := otlpmetrichttp.New(ctx,
        otlpmetrichttp.WithEndpoint("ap-guangzhou.cls.tencentcs.com"),
        otlpmetrichttp.WithHeaders(map[string]string{
            "Authorization": "Basic " + basicAuth("<SecretId>", "<SecretKey>"),
            "topic_id":      "<metric topic_id>",
        }),
    )
    if err != nil {
        panic(err)
    }
    _ = exporter
    // Subsequently, you can periodically upload metrics by attaching the exporter via metric.NewMeterProvider(metric.WithReader(metric.NewPeriodicReader(exporter, ...))).
}
Common Metric Types:
Type
API
Scenario
Counter
Int64Counter / Float64Counter
Monotonically increasing, such as total number of requests
UpDownCounter
Int64UpDownCounter
Can increase or decrease, such as number of connections
Histogram
Float64Histogram
Distribution statistics, such as latency
Gauge (Observer)
Float64ObservableGauge
Instantaneous value, such as CPU utilization
PeriodicReader Configuration Recommendations:
metric.NewPeriodicReader(exporter,
    metric.WithInterval(15*time.Second), // Recommended interval for production: 15~30 seconds
    metric.WithTimeout(5*time.Second),
)

Step 7: Configuring Common Resource Attributes

It is recommended to use a unified Resource for the three types of data to facilitate correlation analysis on the CLS side.
res, _ := resource.New(ctx,
    resource.WithFromEnv(),
    resource.WithProcess(),
    resource.WithTelemetrySDK(),
    resource.WithHost(),
    resource.WithAttributes(
        semconv.ServiceNameKey.String("my-service"),
        semconv.ServiceNamespaceKey.String("Production"),
        semconv.ServiceVersionKey.String("v1.0.0"),
        semconv.DeploymentEnvironmentKey.String("prod"),
    ),
)
Resource Key Field Descriptions:
Field
Description
service.name
Service name, required
service.namespace
Service namespace (such as environment name)
service.version
Service Version

FAQs

Reporting 401 / 403 Authentication Failures

Check whether the AK/SK is correct.
Confirm that the sub-account has been granted CLS write permissions (such as cls:PushLog).
The Authorization header must be in the format Basic <base64(AK:SK)>.

Reporting 404 or topic not found

topic_id and the Endpoint are in different regions. Ensure that the region of the topic matches the region of the Endpoint.

No Data or Data Delay

If a process exits too quickly under SimpleProcessor, the final batch of data may not be sent. Ensure that you call Shutdown.
BatchProcessor has a batching interval, so brief delays are normal.

Whether Endpoint Requires a Protocol Prefix

For the OTLP/HTTP Exporter's WithEndpoint, provide only the domain name. Do not include http:// or https://.
HTTPS is used for reporting by default, so you do not need to explicitly add a protocol option.
If you need to report in cleartext (HTTP), for example in a test environment, you can add the WithInsecure() option.

How to Choose Between Public and Private Network Access Points

Private network (<region>.cls.tencentyun.com): It is recommended for deployments within Tencent Cloud VPCs or CVMs in the same region, as it incurs no public network traffic fees and offers lower latency.
Public network (<region>.cls.tencentcs.com): Use this for local debugging, non-Tencent Cloud environments, or cross-cloud provider environments.
The region of the Endpoint must match the region of the topic_id. Otherwise, a "topic not found" error will be reported.

Cross-Region Reporting

To use a cross-region acceleration access point, add the source region identifier in the request Header:
"x-cross-region": "ap-guangzhou"






Topik sebelumnya: Importing Data from ElasticsearchTopik selanjutnya: Metrics Reporting

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan

Search
    Enter keywords to search documentation