Add histogram explicit boundaries example

Author: drewby

instrumentation-genai/opentelemetry-instrumentation-openai-v2/examples/buckets/.env

@@ -0,0 +1,14 @@
+# Update this with your real OpenAI API key
+OPENAI_API_KEY=sk-YOUR_API_KEY
+
+# Uncomment to use Ollama instead of OpenAI
+# OPENAI_BASE_URL=http://localhost:11434/v1
+# OPENAI_API_KEY=unused
+# CHAT_MODEL=qwen2.5:0.5b
+
+# Uncomment and change to your OTLP endpoint
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+# OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+
+OTEL_SERVICE_NAME=opentelemetry-python-openai
+

instrumentation-genai/opentelemetry-instrumentation-openai-v2/examples/buckets/README.rst

@@ -0,0 +1,38 @@
+OpenTelemetry OpenAI Instrumentation Example
+============================================
+
+This is an example of how to instrument OpenAI calls when configuring OpenTelemetry SDK and Instrumentations manually for metrics.
+
+When `main.py <main.py>`_ is run, it exports metrics to an OTLP compatible endpoint. Metrics include details such as token usage and operation duration, with specific bucket boundaries for each metric.
+
+The bucket boundaries are defined as follows:
+
+- For `gen_ai.client.token.usage`: [1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864]
+- For `gen_ai.client.operation.duration`: [0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92]
+
+These are documented in the `OpenTelemetry GenAI Metrics documentation <https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-metrics/>`_.
+
+Setup
+-----
+
+Minimally, update the `.env <.env>`_ file with your "OPENAI_API_KEY". An OTLP compatible endpoint should be listening for metrics on http://localhost:4317. If not, update "OTEL_EXPORTER_OTLP_ENDPOINT" as well.
+
+Next, set up a virtual environment like this:
+
+::
+
+    python3 -m venv .venv
+    source .venv/bin/activate
+    pip install "python-dotenv[cli]"
+    pip install -r requirements.txt
+
+Run
+---
+
+Run the example like this:
+
+::
+
+    dotenv run -- python main.py
+
+You should see metrics being exported to your configured observability tool, with the specified bucket boundaries for token usage and operation duration.

instrumentation-genai/opentelemetry-instrumentation-openai-v2/examples/buckets/main.py

@@ -0,0 +1,92 @@
+import os
+
+from openai import OpenAI
+
+from opentelemetry import metrics
+from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
+    OTLPMetricExporter,
+)
+from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
+from opentelemetry.sdk.metrics import Histogram, MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.sdk.metrics.view import (
+    ExplicitBucketHistogramAggregation,
+    View,
+)
+
+# configure metrics
+metric_exporter = OTLPMetricExporter()
+metric_reader = PeriodicExportingMetricReader(metric_exporter)
+
+TokenUsageHistogramView = View(
+    instrument_type=Histogram,
+    instrument_name="gen_ai.client.token.usage",
+    aggregation=ExplicitBucketHistogramAggregation(
+        boundaries=[
+            1,
+            4,
+            16,
+            64,
+            256,
+            1024,
+            4096,
+            16384,
+            65536,
+            262144,
+            1048576,
+            4194304,
+            16777216,
+            67108864,
+        ]
+    ),
+)
+
+DurationHistogramView = View(
+    instrument_type=Histogram,
+    instrument_name="gen_ai.client.operation.duration",
+    aggregation=ExplicitBucketHistogramAggregation(
+        boundaries=[
+            0.01,
+            0.02,
+            0.04,
+            0.08,
+            0.16,
+            0.32,
+            0.64,
+            1.28,
+            2.56,
+            5.12,
+            10.24,
+            20.48,
+            40.96,
+            81.92,
+        ]
+    ),
+)
+
+meter_provider = MeterProvider(
+    metric_readers=[metric_reader],
+    views=[TokenUsageHistogramView, DurationHistogramView],
+)
+metrics.set_meter_provider(meter_provider)
+
+# instrument OpenAI
+OpenAIInstrumentor().instrument(meter_provider=meter_provider)
+
+
+def main():
+    client = OpenAI()
+    chat_completion = client.chat.completions.create(
+        model=os.getenv("CHAT_MODEL", "gpt-4o-mini"),
+        messages=[
+            {
+                "role": "user",
+                "content": "Write a short poem on OpenTelemetry.",
+            },
+        ],
+    )
+    print(chat_completion.choices[0].message.content)
+
+
+if __name__ == "__main__":
+    main()

instrumentation-genai/opentelemetry-instrumentation-openai-v2/examples/buckets/requirements.txt

@@ -0,0 +1,5 @@
+openai~=1.57.3
+
+opentelemetry-sdk~=1.29.0
+opentelemetry-exporter-otlp-proto-grpc~=1.29.0
+opentelemetry-instrumentation-openai-v2~=2.0b0