本頁面由 Cloud Translation API 翻譯而成。

使用 OpenTelemetry 設定追蹤記錄收集作業

本文說明如何使用 OpenTelemetry 設定用戶端和端對端追蹤。您必須先設定用戶端追蹤，才能選擇啟用端對端追蹤。詳情請參閱「追蹤記錄收集總覽」。

事前準備

為確保應用程式使用的服務帳戶具備設定追蹤記錄收集作業的必要權限，請要求管理員授予應用程式使用的服務帳戶專案的「Cloud Trace 代理者」 (roles/cloudtrace.agent) IAM 角色。
重要事項：您必須將這個角色授予應用程式使用的服務帳戶，而非使用者帳戶。如果未將角色授予正確的主體，可能會導致權限錯誤。
確認專案已啟用 Cloud Trace API。如要進一步瞭解如何啟用 API，請參閱啟用 API。

設定用戶端追蹤

如要設定用戶端追蹤，您必須匯出追蹤記錄。您可以將追蹤記錄匯出至收集器，或直接匯出至可觀測性後端。您可以使用 OpenTelemetry API 設定追蹤。

使用 OpenTelemetry API 將追蹤記錄匯出至收集器

如要使用 OpenTelemetry API 將追蹤記錄匯出至收集器，請設定 OpenTelemetry SDK 和 OLTP 匯出工具：

使用下列程式碼，將必要依附元件新增至應用程式：

Java

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner</artifactId>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk</artifactId>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk-trace</artifactId>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

Go

go.opentelemetry.io/otel v1.28.0
go.opentelemetry.io/otel/sdk v1.28.0
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.28.0

Node.js

"@opentelemetry/exporter-trace-otlp-grpc": "^0.57.0",
"@opentelemetry/sdk-trace-base": "^1.26.0",
"@opentelemetry/sdk-trace-node": "^1.26.0",

Python

pip install opentelemetry-api opentelemetry-sdk
pip install opentelemetry-exporter-otlp

設定 OpenTelemetry 物件並啟用追蹤功能。

Java

Resource resource = Resource
    .getDefault().merge(Resource.builder().put("service.name", "My App").build());

OtlpGrpcSpanExporter otlpGrpcSpanExporter =
    OtlpGrpcSpanExporter
        .builder()
        .setEndpoint(otlpEndpoint) // Replace with your OTLP endpoint
        .build();

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
    BatchSpanProcessor.builder(otlpGrpcSpanExporter).build();

// Create a new tracer provider
sdkTracerProvider = SdkTracerProvider.builder()
    // Use Otlp exporter or any other exporter of your choice.
    .addSpanProcessor(otlpGrpcSpanProcessor)
    .setResource(resource)
    .setSampler(Sampler.traceIdRatioBased(0.1))
    .build();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
    .setTracerProvider(sdkTracerProvider).build();

// Enable OpenTelemetry traces before Injecting OpenTelemetry
SpannerOptions.enableOpenTelemetryTraces();

// Inject OpenTelemetry object via Spanner options or register as GlobalOpenTelemetry.
SpannerOptions options = SpannerOptions.newBuilder()
    .setOpenTelemetry(openTelemetry)
    .build();
Spanner spanner = options.getService();

Go


// Ensure that your Go runtime version is supported by the OpenTelemetry-Go
// compatibility policy before enabling OpenTelemetry instrumentation.

// Enable OpenTelemetry traces by setting environment variable GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING
// to the case-insensitive value "opentelemetry" before loading the client library.

ctx := context.Background()

// Create a new resource to uniquely identify the application
res, err := resource.Merge(resource.Default(),
	resource.NewWithAttributes(semconv.SchemaURL,
		semconv.ServiceName("My App"),
		semconv.ServiceVersion("0.1.0"),
	))
if err != nil {
	log.Fatal(err)
}

// Create a new OTLP exporter.
defaultOtlpEndpoint := "http://localhost:4317" // Replace with the endpoint on which OTLP collector is running
traceExporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithEndpoint(defaultOtlpEndpoint))
if err != nil {
	log.Fatal(err)
}

// Create a new tracer provider
tracerProvider := sdktrace.NewTracerProvider(
	sdktrace.WithResource(res),
	sdktrace.WithBatcher(traceExporter),
	sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.1)),
)

// Register tracer provider as global
otel.SetTracerProvider(tracerProvider)

Node.js

const {NodeTracerProvider} = require('@opentelemetry/sdk-trace-node');
const {
  OTLPTraceExporter,
} = require('@opentelemetry/exporter-trace-otlp-grpc');
const {
  BatchSpanProcessor,
  TraceIdRatioBasedSampler,
} = require('@opentelemetry/sdk-trace-base');
const {Resource} = require('@opentelemetry/resources');
const {Spanner} = require('@google-cloud/spanner');

// Define a Resource with service metadata
const resource = new Resource({
  'service.name': 'my-service',
  'service.version': '1.0.0',
});

// Create an OTLP gRPC trace exporter
const traceExporter = new OTLPTraceExporter({
  url: 'http://localhost:4317', // Default OTLP gRPC endpoint
});

// Create a provider with a custom sampler
const provider = new NodeTracerProvider({
  sampler: new TraceIdRatioBasedSampler(1.0), // Sample 100% of traces
  resource,
  spanProcessors: [new BatchSpanProcessor(traceExporter)],
});

// Uncomment following line to register tracerProvider globally or pass it in Spanner object
// provider.register();

// Create the Cloud Spanner Client.
const spanner = new Spanner({
  projectId: projectId,
  observabilityOptions: {
    tracerProvider: provider,
    enableExtendedTracing: true,
    enableEndToEndTracing: true,
  },
});

Python

# Setup OpenTelemetry, trace and OTLP exporter.
tracer_provider = TracerProvider(sampler=ALWAYS_ON)
otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4317")
tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))

# Setup the Cloud Spanner Client.
spanner_client = spanner.Client(
    project_id,
    observability_options=dict(tracer_provider=tracer_provider, enable_extended_tracing=True, enable_end_to_end_tracing=True),
)

使用 OpenTelemetry API 直接匯出至可觀測性後端

如要設定 Spanner 用戶端程式庫，直接將追蹤記錄範圍匯出至 Cloud Trace 或其他可觀測性服務供應商後端，請按照下列步驟操作：

使用下列程式碼，將必要依附元件新增至應用程式：

Java

<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-spanner</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-common</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-trace</artifactId>
</dependency>
<dependency>
<groupId>com.google.cloud.opentelemetry</groupId>
<artifactId>exporter-trace</artifactId>
<version>0.30.0</version>
</dependency>

Go

go.opentelemetry.io/otel v1.28.0
go.opentelemetry.io/otel/sdk v1.28.0
github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace v1.24.1

Node.js

"@google-cloud/opentelemetry-cloud-trace-exporter": "^2.4.1",
"@opentelemetry/sdk-trace-base": "^1.26.0",
"@opentelemetry/sdk-trace-node": "^1.26.0",

Python

pip install opentelemetry-api opentelemetry-sdk
pip install opentelemetry-exporter-gcp-trace

設定 OpenTelemetry 物件並啟用追蹤功能。

Java

Resource resource = Resource
    .getDefault().merge(Resource.builder().put("service.name", "My App").build());

SpanExporter traceExporter = TraceExporter.createWithConfiguration(
    TraceConfiguration.builder().setProjectId(projectId).build()
);

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
    BatchSpanProcessor.builder(traceExporter).build();

// Create a new tracer provider
sdkTracerProvider = SdkTracerProvider.builder()
    // Use Otlp exporter or any other exporter of your choice.
    .addSpanProcessor(otlpGrpcSpanProcessor)
    .setResource(resource)
    .setSampler(Sampler.traceIdRatioBased(0.1))
    .build();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
    .setTracerProvider(sdkTracerProvider).build();

// Enable OpenTelemetry traces before Injecting OpenTelemetry
SpannerOptions.enableOpenTelemetryTraces();

// Inject OpenTelemetry object via Spanner options or register it as global object.
// To register as the global OpenTelemetry object,
// use "OpenTelemetrySdk.builder()....buildAndRegisterGlobal()".
SpannerOptions options = SpannerOptions.newBuilder()
    .setOpenTelemetry(openTelemetry)
    .build();
Spanner spanner = options.getService();

Go


// Ensure that your Go runtime version is supported by the OpenTelemetry-Go
// compatibility policy before enabling OpenTelemetry instrumentation.

// Enable OpenTelemetry traces by setting environment variable GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING
// to the case-insensitive value "opentelemetry" before loading the client library.

// Create a new resource to uniquely identify the application
res, err := resource.Merge(resource.Default(),
	resource.NewWithAttributes(semconv.SchemaURL,
		semconv.ServiceName("My App"),
		semconv.ServiceVersion("0.1.0"),
	))
if err != nil {
	log.Fatal(err)
}

// Create a new cloud trace exporter
exporter, err := traceExporter.New(traceExporter.WithProjectID(projectID))
if err != nil {
	log.Fatal(err)
}

// Create a new tracer provider
tracerProvider := sdktrace.NewTracerProvider(
	sdktrace.WithResource(res),
	sdktrace.WithBatcher(exporter),
	sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.1)),
)

// Register tracer provider as global
otel.SetTracerProvider(tracerProvider)

Node.js


const {NodeTracerProvider} = require('@opentelemetry/sdk-trace-node');
const {
  TraceExporter,
} = require('@google-cloud/opentelemetry-cloud-trace-exporter');
const {
  BatchSpanProcessor,
  TraceIdRatioBasedSampler,
} = require('@opentelemetry/sdk-trace-base');
const {Spanner} = require('@google-cloud/spanner');

const traceExporter = new TraceExporter();

// Create a provider with a custom sampler
const provider = new NodeTracerProvider({
  sampler: new TraceIdRatioBasedSampler(1.0), // Sample 100% of traces
  spanProcessors: [new BatchSpanProcessor(traceExporter)],
});

// Uncomment following line to register tracerProvider globally or pass it in Spanner object
// provider.register();

// Set global propagator to propogate the trace context for end to end tracing.
const {propagation} = require('@opentelemetry/api');
const {W3CTraceContextPropagator} = require('@opentelemetry/core');
propagation.setGlobalPropagator(new W3CTraceContextPropagator());

const spanner = new Spanner({
  projectId: projectId,
  observabilityOptions: {
    tracerProvider: provider,
    // Enable extended tracing to allow your SQL statements to be annotated.
    enableExtendedTracing: true,
    // Enable end to end tracing.
    enableEndToEndTracing: true,
  },
});

Python

# Setup OpenTelemetry, trace and Cloud Trace exporter.
tracer_provider = TracerProvider(sampler=ALWAYS_ON)
trace_exporter = CloudTraceSpanExporter(project_id=project_id)
tracer_provider.add_span_processor(BatchSpanProcessor(trace_exporter))

# Setup the Cloud Spanner Client.
spanner_client = spanner.Client(
    project_id,
    observability_options=dict(tracer_provider=tracer_provider, enable_extended_tracing=True, enable_end_to_end_tracing=True),
)

設定端對端追蹤

本節說明如何在 Spanner 用戶端程式庫中設定端對端追蹤：

使用下列程式碼，將必要依附元件新增至應用程式：

Java

現有的用戶端追蹤依附元件足以設定端對端追蹤。不需要任何額外的依附元件。

Go

除了用戶端追蹤所需的依附元件外，您還需要下列依附元件：
go.opentelemetry.io/otel/propagation v1.28.0

Node.js

現有的用戶端追蹤依附元件足以設定端對端追蹤。不需要任何額外的依附元件。

Python

現有的用戶端追蹤依附元件足以設定端對端追蹤。不需要任何額外的依附元件。

啟用端對端追蹤。

Java

SpannerOptions options = SpannerOptions.newBuilder()
  .setOpenTelemetry(openTelemetry)
  .setEnableEndToEndTracing(/* enableEndtoEndTracing= */ true)
  .build();

Go

如要啟用這項功能，請在用戶端設定中使用 EnableEndToEndTracing 選項。

client, _ := spanner.NewClientWithConfig(ctx, "projects/test-project/instances/test-instance/databases/test-db", spanner.ClientConfig{
SessionPoolConfig: spanner.DefaultSessionPoolConfig,
EnableEndToEndTracing:      true,
}, clientOptions...)

Node.js

const spanner = new Spanner({
projectId: projectId,
observabilityOptions: {
tracerProvider: openTelemetryTracerProvider,
enableEndToEndTracing: true,
}
})

Python

observability_options = dict(
tracer_provider=tracer_provider,
enable_end_to_end_tracing=True,
)
spanner = spanner.Client(project_id, observability_options=observability_options)

在 OpenTelemetry 中設定追蹤記錄脈絡傳播。

Java

OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
  .setTracerProvider(sdkTracerProvider)
  .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
  .buildAndRegisterGlobal();

Go

// Register the TraceContext propagator globally.
otel.SetTextMapPropagator(propagation.TraceContext{})

Node.js

const {propagation} = require('@opentelemetry/api');
const {W3CTraceContextPropagator} = require('@opentelemetry/core');
propagation.setGlobalPropagator(new W3CTraceContextPropagator());

Python

from opentelemetry.propagate import set_global_textmap
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
set_global_textmap(TraceContextTextMapPropagator())

端對端追蹤屬性

端對端追蹤記錄可能包含下列資訊：

屬性名稱	說明
service.name	屬性值一律為 `spanner_api_frontend`。
cloud.region	Google Cloud Spanner API 前端的雲端區域，負責處理應用程式要求。
gcp.spanner.server.query.fingerprint	屬性值為查詢指紋。如要進一步偵錯這項查詢，請參閱「Query statistics tables」(查詢統計資料表) 中的 `TEXT_FINGERPRINT` 資料欄。
gcp.spanner.server.paxos.participantcount	交易的參與者人數。詳情請參閱「Cloud Spanner 的讀取與寫入」。

追蹤記錄範例

端對端追蹤記錄可讓您查看下列詳細資料：

應用程式與 Spanner 之間的延遲時間。您可以計算網路延遲，確認是否有任何網路問題。
應用程式要求所使用的 Spanner API 前端雲端區域。您可以使用這項功能，檢查應用程式與 Spanner 之間的跨區域呼叫。

在下列範例中，您的應用程式要求是由 us-west1 地區的 Spanner API 前端提供服務，網路延遲時間為 8.542 毫秒 (55.47 毫秒 - 46.928 毫秒)。

查看端對端追蹤記錄。

後續步驟

如要進一步瞭解 OpenTelemetry，請參閱 OpenTelemetry 說明文件。

使用 OpenTelemetry 設定追蹤記錄收集作業 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

設定用戶端追蹤

使用 OpenTelemetry API 將追蹤記錄匯出至收集器

Java

Go

Node.js

Python

Java

Go

Node.js

Python

使用 OpenTelemetry API 直接匯出至可觀測性後端

Java

Go

Node.js

Python

Java

Go

Node.js

Python

設定端對端追蹤

Java

Go

Node.js

Python

Java

Go

Node.js

Python

Java

Go

Node.js

Python

端對端追蹤屬性

追蹤記錄範例

後續步驟

使用 OpenTelemetry 設定追蹤記錄收集作業