Skip to content

README.md

Latest commit

 

History

History
113 lines (93 loc) · 8.87 KB

README.md

File metadata and controls

113 lines (93 loc) · 8.87 KB

API Reference

A comprehensive reference for the public API provided by the @aio-lib-telemetry library.

Available Imports

These are all the imports you can get from this library when importing from @adobe/aio-lib-telemetry.

import {
  // Configuration
  defineTelemetryConfig,
  defineMetrics,

  // Configuration Helpers
  getAioRuntimeAttributes,
  getAioRuntimeResource,
  getAioRuntimeResourceWithAttributes,
  getPresetInstrumentations,

  // Tracing Helpers
  getActiveSpan,
  tryGetActiveSpan,
  addEventToActiveSpan,
  serializeContextIntoCarrier,
  deserializeContextFromCarrier,

  // Instrumentation
  instrument,
  instrumentEntrypoint,
  getInstrumentationHelpers,

  // Logging
  getLogger,

  // Global Telemetry API
  getGlobalTelemetryApi,
} from "@adobe/aio-lib-telemetry";

OpenTelemetry API

OpenTelemetry features a modular architecture consisting of over 25 packages, which can make importing specific APIs rather complex. To streamline this process, our library offers a convenient "meta-package" otel import path. This allows you to import all the necessary OpenTelemetry APIs from a single source, simplifying the setup.

While this does not include every OpenTelemetry API, it covers the most common ones you will need in your code. If you find any essential APIs missing, feel free to open an issue or submit a PR. You can also import the APIs you need from the individual OpenTelemetry packages, but this is a convenient way to import all the APIs you need in a single import.

Tip

When working with OpenTelemetry exporters, you have three protocols to choose from:

  • OTLP/GRPC, OTLP/HTTP, and OTLP/Proto

The official packages use the same class name for exporters across all protocols, which can make it tricky to pick the right one or get reliable auto-completion. To help with this, our library re-exports them with clear protocol suffixes, for example:

  • OTLPTraceExporter from @opentelemetry/exporter-trace-otlp-http -> OTLPTraceExporterHttp
  • OTLPTraceExporter from @opentelemetry/exporter-trace-otlp-grpc -> OTLPTraceExporterGrpc
  • OTLPTraceExporter from @opentelemetry/exporter-trace-otlp-proto -> OTLPTraceExporterProto

Using them is the same as using the original class, but with a more predictable and consistent naming convention.

import {
  // Import all the OpenTelemetry APIs you need
  SimpleSpanProcessor,
  CompressionAlgorithm,
  OTLPTraceExporterProto,
  OTLPMetricExporterHttp,
  OTLPLogExporterGrpc,
  // ...
} from "@adobe/aio-lib-telemetry/otel";

Interfaces

Interface Description
EntrypointInstrumentationConfig The configuration for entrypoint instrumentation.
TelemetryConfig The configuration options for the telemetry module.

Type Aliases

Type Alias Description
DiagnosticsLogLevel Available log levels for the OpenTelemetry DiagLogger.
EntrypointFunction The shape of the entrypoint function.
InstrumentationConfig The configuration for instrumentation.
InstrumentationContext The context for the current operation.
TelemetryApi Defines the global telemetry API. These items should be set once per application.
TelemetryDiagnosticsConfig The configuration for the telemetry diagnostics.
TelemetryInstrumentationPreset Defines the names of available instrumentation presets.
TelemetryIntegration A telemetry integration.
TelemetryPropagationConfig Configuration related to context propagation (for distributed tracing).

Functions

Function Description
addEventToActiveSpan Adds an event to the given span.
defineMetrics Helper to define a record of metrics.
defineTelemetryConfig Helper to define the telemetry configuration for an entrypoint.
deserializeContextFromCarrier Deserializes the context from a carrier and augments the given base context with it.
getActiveSpan Gets the active span from the given context.
getAioRuntimeAttributes biome-ignore-all lint/performance/noBarrelFile: This is the import entrypoint for the public API.
getAioRuntimeResource biome-ignore-all lint/performance/noBarrelFile: This is the import entrypoint for the public API.
getAioRuntimeResourceWithAttributes biome-ignore-all lint/performance/noBarrelFile: This is the import entrypoint for the public API.
getGlobalTelemetryApi Gets the global telemetry API.
getInstrumentationHelpers Access helpers for the current instrumented operation.
getLogger Gets a logger instance that can export OpenTelemetry logs.
getPresetInstrumentations Gets the instrumentations for a given preset.
instrument Instruments a function.
instrumentEntrypoint Instruments the entrypoint of a runtime action. Needs to be used ONLY with the main function of a runtime action.
serializeContextIntoCarrier Serializes the current context into a carrier.
tryAddEventToActiveSpan Tries to add an event to the active span.
tryGetActiveSpan Tries to get the active span from the given context.