OpenTelemetry Attributes in Python

When performing root cause analysis, span attributes are an important tool for pinpointing the source of performance issues.

Setting Attributes

Note that it is only possible to set attributes, not to get them.

Much like how resources are used to describe your services, attributes are used to describe your spans. Here is an example of setting attributes to correctly define an HTTP client request:

span = tracer.start_span(
  "/project/:project-id/list",
  kind=SpanKind.CLIENT,
  attributes={
    "http.method": "GET",
    "http.flavor": "1.1",
    "http.url": "https://example.com:8080/project/123/list/?page=2",
    "net.peer.ip": "192.0.2.5",
    "http.status_code": 200,
    "http.status_text": "OK"
  },
)

# In addition to the standard attributes, custom attributes can be added as well.
span.set_attribute("list.page_number", 2);

// To avoid collisions, always namespace your attribute keys using dot notation.
span.set_attribute("project.id", 2);

// attributes can be added to a span at any time before the span is finished.
span.end()

Conventions

Spans represent specific operations in and between systems. Many operations represent well-known protocols like HTTP or database calls. Like with resources, OpenTelemetry defines a schema for the attributes which describe these common operations. These standards are called Semantic Conventions, and are defined in the OpenTelemetry Specification.

OpenTelemetry provides a schema for describing common attributes so that backends can easily parse and identify relevant information. It is important to understand these conventions when writing instrumentation, in order to normalize your data and increase its utility.

The following semantic conventions are defined for tracing:

  • General: General semantic attributes that may be used in describing different kinds of operations.
  • HTTP: Spans for HTTP client and server.
  • Database: Spans for SQL and NoSQL client calls.
  • RPC/RMI: Spans for remote procedure calls (e.g., gRPC).
  • Messaging: Spans for interaction with messaging systems (queues, publish/subscribe, etc.).
  • FaaS: Spans for Function as a Service (e.g., AWS Lambda).