技术手册

本页面为常见场景提供了一个技术手册。

创建新的 span

from opentelemetry import trace

tracer = trace.get_tracer("my.tracer")
with tracer.start_as_current_span("print") as span:
    print("foo")
    span.set_attribute("printed_string", "foo")

获取和修改 span

from opentelemetry import trace

current_span = trace.get_current_span()
current_span.set_attribute("hometown", "Seattle")

创建嵌套 span

from opentelemetry import trace
import time

tracer = trace.get_tracer("my.tracer")

# 创建一个用于跟踪某些工作的新 span
with tracer.start_as_current_span("parent"):
    time.sleep(1)

    # 创建一个嵌套的 span 以跟踪嵌套的工作
    with tracer.start_as_current_span("child"):
        time.sleep(2)
        # 嵌套的 span 在超出范围时关闭

    # 现在父 span 再次成为当前 span
    time.sleep(1)

    # 这个 span 也在超出范围时关闭

在不同的上下文中捕获 baggage

from opentelemetry import trace, baggage

tracer = trace.get_tracer("my.tracer")
with tracer.start_as_current_span(name="root span") as root_span:
    parent_ctx = baggage.set_baggage("context", "parent")
    with tracer.start_as_current_span(
        name="child span", context=parent_ctx
    ) as child_span:
        child_ctx = baggage.set_baggage("context", "child")

print(baggage.get_baggage("context", parent_ctx))
print(baggage.get_baggage("context", child_ctx))

手动设置 span 上下文

通常,您的应用程序或服务框架会自动处理传播跟踪上下文的工作。但在某些情况下,您可能需要自己保存跟踪上下文(使用 .inject)并在其他地方恢复它(使用 .extract)。

from opentelemetry import trace, context
from opentelemetry.trace import NonRecordingSpan, SpanContext, TraceFlags
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator

# 配置一个简单的处理器将 span 写入控制台,以便我们可以看到正在发生的情况。
trace.set_tracer_provider(TracerProvider())
trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

tracer = trace.get_tracer("my.tracer")

# 默认情况下,TextMapPropagator 使用任何类似字典的对象作为其载体。您还可以实现自定义的获取器和设置器。
with tracer.start_as_current_span('first-trace'):
    carrier = {}
    # 将当前上下文写入载体中。
    TraceContextTextMapPropagator().inject(carrier)

# 下面的代码可能在不同的线程、不同的机器等位置执行。
# 典型情况下,它会在不同的微服务中执行,并且携带者会通过 HTTP 标头进行转发。

# 从载体中提取跟踪上下文。
# 这是一个典型的载体的样子,它会在上面的代码中被注入。
carrier = {'traceparent': '00-a9c3b99a95cc045e573e163c3ac80a77-d99d251a8caecd06-01'}
# 然后,我们使用传播器从中获取上下文。
ctx = TraceContextTextMapPropagator().extract(carrier=carrier)

# 如果您已经拥有 SpanContext 对象,而不是从载体中提取跟踪上下文,您可以通过如下方式获取跟踪上下文。
span_context = SpanContext(
    trace_id=2604504634922341076776623263868986797,
    span_id=5213367945872657620,
    is_remote=True,
    trace_flags=TraceFlags(0x01)
)
ctx = trace.set_span_in_context(NonRecordingSpan(span_context))

# 现在有几种方法可以使用跟踪上下文。

# 可以在启动 span 时传递上下文对象。
with tracer.start_as_current_span('child', context=ctx) as span:
    span.set_attribute('primes', [2, 3, 5, 7])

# 或者可以将它设置为当前上下文,下一个 span 将使用它。
# 返回的令牌可以用于恢复先前的上下文。
token = context.attach(ctx)
try:
    with tracer.start_as_current_span('child') as span:
        span.set_attribute('evens', [2, 4, 6, 8])
finally:
    context.detach(token)

使用具有不同 Resource 的多个 tracer 提供程序

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor

# 只能设置一次的全局 tracer 提供程序
trace.set_tracer_provider(
    TracerProvider(resource=Resource.create({"service.name": "service1"}))
)
trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

tracer = trace.get_tracer("tracer.one")
with tracer.start_as_current_span("some-name") as span:
    span.set_attribute("key", "value")



another_tracer_provider = TracerProvider(
    resource=Resource.create({"service.name": "service2"})
)
another_tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

another_tracer = trace.get_tracer("tracer.two", tracer_provider=another_tracer_provider)
with another_tracer.start_as_current_span("name-here") as span:
    span.set_attribute("another-key", "another-value")
最后修改 December 10, 2023: translate (a4350d6e)