OpenTelemetry Writer Instrumentation for Traceloop SDK

Warnings

• gotcha This instrumentation package explicitly depends on and instruments components of the `traceloop-sdk`. Installing `opentelemetry-instrumentation-writer` alone will not generate any traces unless `traceloop-sdk` is also installed and actively used within your application.
  Fix: Ensure `traceloop-sdk` is installed (`pip install traceloop-sdk`) and integrated into your LLM application for this instrumentation to have an effect.
• breaking The OpenTelemetry Generative AI Semantic Conventions are evolving rapidly. This means that span attribute names, types, and structures emitted by this instrumentation can change frequently between minor and even patch versions, requiring updates to any custom trace processing or analysis logic.
  Fix: Regularly consult the OpenTelemetry GenAI Semantic Conventions documentation and the `openllmetry` release notes. Update your trace consumers and dashboards to reflect the latest attribute specifications.
• gotcha The `WriterInstrumentor` targets `traceloop.sdk.tracing.writer.WriterModule`, which is an internal component of `traceloop-sdk`. Users typically do not directly interact with `WriterModule`. Traces are generated implicitly when using `traceloop-sdk`'s higher-level functionalities, such as LLM wrappers or agents.
  Fix: Understand that this instrumentation operates at a low level within the `traceloop-sdk`. To see its effects, integrate and use `traceloop-sdk` as documented, and observe the resulting spans rather than trying to directly invoke the `WriterModule`.

Install

• pip install opentelemetry-instrumentation-writer Install package

Imports

• WriterInstrumentor

  from opentelemetry.instrumentation.writer import WriterInstrumentor

Quickstart

This quickstart demonstrates how to manually initialize OpenTelemetry, enable the `WriterInstrumentor`, and explains that traces will be generated when the `traceloop-sdk`'s internal `writer` module is used. This instrumentation is typically part of the broader `Traceloop.init()` setup, but can be enabled standalone.

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

# NOTE: This instrumentation requires 'traceloop-sdk' to be installed
# and its internal 'writer' components to be used to generate traces.
# You would typically install it via `pip install traceloop-sdk`.

# Optional: Also install a specific LLM library like openai, anthropic, etc.
# e.g., pip install opentelemetry-instrumentation-openai

# 1. Import the specific instrumentation
from opentelemetry.instrumentation.writer import WriterInstrumentor

# 2. Set up a basic OpenTelemetry TracerProvider and Exporter
resource = Resource.create({"service.name": "my-traceloop-writer-app"})
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# 3. Instrument the target library
WriterInstrumentor().instrument()

# 4. Now, if `traceloop-sdk` is used, operations involving its internal
#    'writer' module (e.g., handling LLM inputs/outputs) will generate spans.
#    For example, if you were using `traceloop-sdk` to wrap an OpenAI call:
#
# from traceloop.sdk import Traceloop
# from openai import OpenAI
# Traceloop.init(app_name="my-llm-app", disable_batch=True) # Enables ALL Traceloop instrumentations
# client = OpenAI()
# response = client.chat.completions.create(
#    model="gpt-3.5-turbo", messages=[{"role": "user", "content": "Hello"}]
# )
# print(response.choices[0].message.content)

print("OpenTelemetry Writer Instrumentation enabled. Traces will appear when traceloop-sdk 'writer' module is invoked.")