OpenTelemetry Attributes in Java

When performing root cause analysis, span attributes are an important tool for pinpointing the source of performance issues. Much like how resources are used to describe your services, attributes are used to describe your spans.

Setting Attributes

Here is an example of setting attributes to define an HTTP client request:

// This span represents the request.
Span span = tracer.spanBuilder("/project/:project-id/list") // operation named after the route
                 .setSpanKind(Span.Kind.CLIENT) // tag the span as a service boundary
                 .startSpan();

// The following attributes represent an HTTP client request
span.setAttribute(SemanticAttributes.HTTP_METHOD, "GET");
span.setAttribute(SemanticAttributes.HTTP_FLAVOR, "1.1");
span.setAttribute(SemanticAttributes.HTTP_URL, "https://example.com:8080/project/123/list/?page=2");
span.setAttribute(SemanticAttributes.NET_PEER_IP, "192.0.2.5");
span.setAttribute(SemanticAttributes.HTTP_STATUS_CODE, 200);
span.setAttribute(SemanticAttributes.HTTP_STATUS_TEXT,"OK");

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

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

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

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

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).