Skip to main content
Hello OTel client experts — in this lesson we’ll examine how OpenTelemetry clients are layered and how the pieces relate. This article keeps the original ordering and diagrams while clarifying responsibilities, common patterns, and best practices for instrumentation authors and runtime operators.
OpenTelemetry defines a vendor-agnostic model for telemetry signals: traces, metrics, logs, and baggage. Each signal follows a consistent layering pattern — Instrumentation, Semantic Conventions, API, SDK, and Contrib — which separates the contract from runtime behavior and integrations.
Overview
  • OpenTelemetry (https://opentelemetry.io/) standardizes telemetry signals (traces, metrics, logs) and cross-process baggage.
  • For each signal you typically have:
    • Instrumentation — application or framework code that emits telemetry.
    • Semantic conventions — standardized attribute/metric/log keys and meanings.
    • API — the public contract used by instrumentation to create telemetry.
    • SDK — runtime implementation that handles sampling, aggregation, batching, and exporting.
    • Contrib — integration packages, auto-instrumentation, and vendor exporters.
Table: Signal responsibilities at a glance
SignalInstrumentationSemantic ConventionsAPISDKContrib / Examples
TracesCreate and end spans in application codehttp.method, db.statementTracer API to create/manage spansSampling, batching, exporting spansAuto-instrumentation, exporters (e.g., Jaeger)
MetricsEmit counters/histograms/gaugeshttp.server.duration, process.cpu.timeMeter API for counters/histograms/gaugesAggregation, temporality, exportPrometheus exporters/instrumentation
LogsEmit structured log recordslog.record.original, log.file.path.resolvedLogger API for structured logsProcessing, enrichment, batching, exportFluentd exporters, bridges
BaggageAttach key/value pairs to contextsNaming conventions for keysBaggage API for get/setPropagation storage and context managementPropagators (B3, Jaeger, W3C Trace Context)
Traces
  • Instrumentation: application code or instrumented libraries create spans representing operations.
  • Semantic conventions: standard attributes such as http.method and db.statement ensure consistent meaning across services and languages.
  • Tracer API: the stable contract libraries and apps call to create and manage spans.
  • SDK: implements runtime behavior — sampling policies, span processors (batching/exporting), and the exporter to backends.
  • Contrib: integration packages and exporters (for example, Flask instrumentation or Jaeger exporter).
Metrics
  • Emitted similarly to traces, but as numerical time-series.
  • Semantic conventions: standard metric names (e.g., http.server.duration) and units.
  • Meter API: defines counters, histograms, and gauges as the instrumentation contract.
  • SDK: implements aggregation, temporality, and exporting of metric data.
  • Contrib: exporters and integrations such as Prometheus instrumentation.
Logs
  • Application code and frameworks can emit structured logs as a first-class signal.
  • Semantic conventions standardize log fields to enable correlation with traces and metrics.
  • Logger API: how structured logs are created and annotated.
  • SDK: log processors, enrichers, batching, and exporters.
  • Contrib: log exporters and bridge packages (e.g., Fluentd).
Baggage
  • Baggage is for propagating small, application-defined key/value pairs (for example, user.id or session.id) across process boundaries.
  • Pattern: API defines how to set/get baggage; SDK supports context storage and propagation; contrib supplies propagators and integrations (B3, Jaeger, W3C Trace Context).
  • In many cases, built-in OTel propagators meet common baggage needs.
The common design principle
  • All signals follow the same architectural pattern:
    • API = “what” the instrumentation emits (stable contract).
    • SDK = “how” telemetry is processed and delivered (runtime).
    • Contrib = ecosystem integrations and exporters.
  • This separation preserves stable instrumentation while allowing flexible runtime implementations.
The image is a diagram titled "OpenTelemetry Client Architecture by Layer," illustrating different components and layers like Traces, Metrics, Logs, and Baggage, along with their respective APIs, SDKs, and Contribs.
Best practice: instrumentation libraries should depend only on the API and semantic conventions. The SDK is an implementation detail that varies by deployment. Coupling libraries to the SDK reduces portability.
Do not import or rely on SDK internals from instrumentation libraries. Instrumentation should use the OpenTelemetry API (and semantic conventions) only. The SDK can be configured by the application or platform at runtime.
Quizzes
  1. What makes OpenTelemetry a cross-cutting concern?
  • It only works with front-end code.
  • It provides centralized logging only.
  • It is mixed into multiple parts of the application to provide observability.
  • It replaces business logic in application layers.
Answer: It is mixed into multiple parts of the application to provide observability. Explanation: Cross-cutting concerns—like telemetry, logging, authentication, and error handling—touch multiple layers and modules rather than being confined to a single component. Observability must be present across UI, business logic, and data-access layers, so it cuts across the clean boundaries defined by Separation of Concerns.
The image is a quiz question asking what makes OpenTelemetry a cross-cutting concern, with four multiple-choice options. Option 3 is highlighted in red as the correct answer.
  1. Which software design principle is challenged by cross-cutting concerns like OpenTelemetry?
  • Inheritance
  • Separation of Concerns
  • Single Responsibility Principle
  • Encapsulation
Answer: Separation of Concerns. Explanation: Cross-cutting concerns must be applied across modules and layers, which complicates strict isolation of responsibilities that Separation of Concerns aims to achieve.
The image is a quiz question asking which software design principle is challenged by cross-cutting concerns like OpenTelemetry. It provides four options: Inheritance, Separation of Concerns, Single Responsibility Principle, and Encapsulation.
  1. What is the main purpose of the OpenTelemetry API in the client architecture?
  • To export telemetry to a vendor backend?
  • To define cross-cutting interfaces and constants for instrumentation.
  • To store metrics in a database.
  • To monitor OpenTelemetry itself.
Answer: To define cross-cutting interfaces and constants for instrumentation. Explanation: The API defines the contract that libraries and applications use to create telemetry in a vendor-agnostic way, keeping instrumentation stable even when the SDK or exporters change.
The image is a quiz question about the main purpose of the OpenTelemetry API in client architecture, offering four possible answers.
  1. Which part of the OpenTelemetry client should NOT be used inside instrumentation libraries?
  • Semantic conventions
  • API
  • SDK
  • Constants
Answer: SDK. Explanation: Instrumentation libraries should depend only on the OpenTelemetry API (and conventions/constants). The SDK is an implementation detail and may vary by deployment; coupling libraries to the SDK reduces portability.
The image is a quiz question asking which part of the OpenTelemetry client should not be used inside instrumentation libraries, with answer options: Semantic Conventions, API, SDK, and Constants.
  1. Which of the following best describes the role of semantic conventions in OpenTelemetry?
  • Provide a UI for visualizing telemetry
  • Define standard attribute keys and values for consistent telemetry
  • Authenticate telemetry between services
  • Automatically deploy OTel agents
Answer: Define standard attribute keys and values for consistent telemetry. Explanation: Semantic conventions standardize the names and meanings of attributes, metrics, and log fields so data from different services and languages can be understood and correlated consistently. That’s it for this lesson. Links and references

Watch Video