genai-otel-instrument 0.1.1.dev0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of genai-otel-instrument might be problematic. Click here for more details.

Files changed (44) hide show
  1. genai_otel/__init__.py +129 -0
  2. genai_otel/__version__.py +34 -0
  3. genai_otel/auto_instrument.py +413 -0
  4. genai_otel/cli.py +92 -0
  5. genai_otel/config.py +187 -0
  6. genai_otel/cost_calculator.py +276 -0
  7. genai_otel/exceptions.py +17 -0
  8. genai_otel/gpu_metrics.py +240 -0
  9. genai_otel/instrumentors/__init__.py +47 -0
  10. genai_otel/instrumentors/anthropic_instrumentor.py +134 -0
  11. genai_otel/instrumentors/anyscale_instrumentor.py +27 -0
  12. genai_otel/instrumentors/aws_bedrock_instrumentor.py +94 -0
  13. genai_otel/instrumentors/azure_openai_instrumentor.py +69 -0
  14. genai_otel/instrumentors/base.py +528 -0
  15. genai_otel/instrumentors/cohere_instrumentor.py +76 -0
  16. genai_otel/instrumentors/google_ai_instrumentor.py +87 -0
  17. genai_otel/instrumentors/groq_instrumentor.py +106 -0
  18. genai_otel/instrumentors/huggingface_instrumentor.py +97 -0
  19. genai_otel/instrumentors/langchain_instrumentor.py +75 -0
  20. genai_otel/instrumentors/llamaindex_instrumentor.py +36 -0
  21. genai_otel/instrumentors/mistralai_instrumentor.py +119 -0
  22. genai_otel/instrumentors/ollama_instrumentor.py +83 -0
  23. genai_otel/instrumentors/openai_instrumentor.py +241 -0
  24. genai_otel/instrumentors/replicate_instrumentor.py +42 -0
  25. genai_otel/instrumentors/togetherai_instrumentor.py +42 -0
  26. genai_otel/instrumentors/vertexai_instrumentor.py +42 -0
  27. genai_otel/llm_pricing.json +589 -0
  28. genai_otel/logging_config.py +45 -0
  29. genai_otel/mcp_instrumentors/__init__.py +14 -0
  30. genai_otel/mcp_instrumentors/api_instrumentor.py +144 -0
  31. genai_otel/mcp_instrumentors/base.py +105 -0
  32. genai_otel/mcp_instrumentors/database_instrumentor.py +336 -0
  33. genai_otel/mcp_instrumentors/kafka_instrumentor.py +31 -0
  34. genai_otel/mcp_instrumentors/manager.py +139 -0
  35. genai_otel/mcp_instrumentors/redis_instrumentor.py +31 -0
  36. genai_otel/mcp_instrumentors/vector_db_instrumentor.py +265 -0
  37. genai_otel/metrics.py +148 -0
  38. genai_otel/py.typed +2 -0
  39. genai_otel_instrument-0.1.1.dev0.dist-info/METADATA +463 -0
  40. genai_otel_instrument-0.1.1.dev0.dist-info/RECORD +44 -0
  41. genai_otel_instrument-0.1.1.dev0.dist-info/WHEEL +5 -0
  42. genai_otel_instrument-0.1.1.dev0.dist-info/entry_points.txt +2 -0
  43. genai_otel_instrument-0.1.1.dev0.dist-info/licenses/LICENSE +201 -0
  44. genai_otel_instrument-0.1.1.dev0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,463 @@
1
+ Metadata-Version: 2.4
2
+ Name: genai-otel-instrument
3
+ Version: 0.1.1.dev0
4
+ Summary: Comprehensive OpenTelemetry auto-instrumentation for LLM/GenAI applications
5
+ Author-email: Kshitij Thakkar <kshitijthakkar@rocketmail.com>
6
+ License: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/Mandark-droid/genai_otel_instrument
8
+ Project-URL: Repository, https://github.com/Mandark-droid/genai_otel_instrument
9
+ Project-URL: Documentation, https://github.com/Mandark-droid/genai_otel_instrument#readme
10
+ Project-URL: Issues, https://github.com/Mandark-droid/genai_otel_instrument/issues
11
+ Project-URL: Changelog, https://github.com/Mandark-droid/genai_otel_instrument/blob/main/CHANGELOG.md
12
+ Keywords: opentelemetry,observability,llm,genai,instrumentation,tracing,metrics,monitoring
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
16
+ Classifier: Topic :: System :: Monitoring
17
+ Classifier: License :: OSI Approved :: Apache Software License
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.9
21
+ Classifier: Programming Language :: Python :: 3.10
22
+ Classifier: Programming Language :: Python :: 3.11
23
+ Classifier: Programming Language :: Python :: 3.12
24
+ Requires-Python: >=3.9
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Requires-Dist: opentelemetry-api<2.0.0,>=1.20.0
28
+ Requires-Dist: opentelemetry-sdk<2.0.0,>=1.20.0
29
+ Requires-Dist: opentelemetry-instrumentation>=0.41b0
30
+ Requires-Dist: opentelemetry-semantic-conventions<1.0.0,>=0.45b0
31
+ Requires-Dist: opentelemetry-exporter-otlp>=1.20.0
32
+ Requires-Dist: opentelemetry-instrumentation-requests>=0.41b0
33
+ Requires-Dist: opentelemetry-instrumentation-httpx>=0.41b0
34
+ Requires-Dist: requests>=2.20.0
35
+ Requires-Dist: wrapt>=1.14.0
36
+ Requires-Dist: httpx>=0.23.0
37
+ Requires-Dist: opentelemetry-instrumentation-mysql>=0.41b0
38
+ Requires-Dist: mysql-connector-python<9.0.0,>=8.0.0
39
+ Requires-Dist: opentelemetry-instrumentation-psycopg2>=0.41b0
40
+ Requires-Dist: psycopg2-binary>=2.9.0
41
+ Requires-Dist: opentelemetry-instrumentation-redis>=0.41b0
42
+ Requires-Dist: redis
43
+ Requires-Dist: opentelemetry-instrumentation-pymongo>=0.41b0
44
+ Requires-Dist: pymongo
45
+ Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.41b0
46
+ Requires-Dist: sqlalchemy>=1.4.0
47
+ Requires-Dist: opentelemetry-instrumentation-kafka-python>=0.41b0
48
+ Requires-Dist: kafka-python
49
+ Provides-Extra: openinference
50
+ Requires-Dist: openinference-instrumentation==0.1.31; extra == "openinference"
51
+ Requires-Dist: openinference-instrumentation-litellm==0.1.19; extra == "openinference"
52
+ Requires-Dist: openinference-instrumentation-mcp==1.3.0; extra == "openinference"
53
+ Requires-Dist: openinference-instrumentation-smolagents==0.1.11; extra == "openinference"
54
+ Requires-Dist: litellm>=1.0.0; extra == "openinference"
55
+ Provides-Extra: gpu
56
+ Requires-Dist: nvidia-ml-py>=11.495.46; extra == "gpu"
57
+ Requires-Dist: codecarbon>=2.3.0; extra == "gpu"
58
+ Provides-Extra: co2
59
+ Requires-Dist: codecarbon>=2.3.0; extra == "co2"
60
+ Provides-Extra: openai
61
+ Requires-Dist: openai>=1.0.0; extra == "openai"
62
+ Provides-Extra: anthropic
63
+ Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
64
+ Provides-Extra: google
65
+ Requires-Dist: google-generativeai>=0.3.0; extra == "google"
66
+ Provides-Extra: aws
67
+ Requires-Dist: boto3>=1.28.0; extra == "aws"
68
+ Provides-Extra: azure
69
+ Requires-Dist: azure-ai-openai>=1.0.0; extra == "azure"
70
+ Provides-Extra: cohere
71
+ Requires-Dist: cohere>=4.0.0; extra == "cohere"
72
+ Provides-Extra: mistral
73
+ Requires-Dist: mistralai>=0.4.2; extra == "mistral"
74
+ Provides-Extra: together
75
+ Requires-Dist: together>=0.2.0; extra == "together"
76
+ Provides-Extra: groq
77
+ Requires-Dist: groq>=0.4.0; extra == "groq"
78
+ Provides-Extra: ollama
79
+ Requires-Dist: ollama>=0.1.0; extra == "ollama"
80
+ Provides-Extra: replicate
81
+ Requires-Dist: replicate>=0.15.0; extra == "replicate"
82
+ Provides-Extra: langchain
83
+ Requires-Dist: langchain>=0.1.0; extra == "langchain"
84
+ Provides-Extra: llamaindex
85
+ Requires-Dist: llama-index>=0.9.0; extra == "llamaindex"
86
+ Provides-Extra: huggingface
87
+ Requires-Dist: transformers>=4.30.0; extra == "huggingface"
88
+ Provides-Extra: databases
89
+ Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.41b0; extra == "databases"
90
+ Requires-Dist: sqlalchemy>=1.4.0; extra == "databases"
91
+ Requires-Dist: opentelemetry-instrumentation-redis>=0.41b0; extra == "databases"
92
+ Requires-Dist: redis; extra == "databases"
93
+ Requires-Dist: opentelemetry-instrumentation-pymongo>=0.41b0; extra == "databases"
94
+ Requires-Dist: pymongo; extra == "databases"
95
+ Requires-Dist: opentelemetry-instrumentation-psycopg2>=0.41b0; extra == "databases"
96
+ Requires-Dist: psycopg2-binary>=2.9.0; extra == "databases"
97
+ Requires-Dist: opentelemetry-instrumentation-mysql>=0.41b0; extra == "databases"
98
+ Requires-Dist: mysql-connector-python<9.0.0,>=8.0.0; extra == "databases"
99
+ Provides-Extra: messaging
100
+ Requires-Dist: opentelemetry-instrumentation-kafka-python>=0.41b0; extra == "messaging"
101
+ Requires-Dist: kafka-python; extra == "messaging"
102
+ Provides-Extra: vector-dbs
103
+ Requires-Dist: pinecone>=3.0.0; extra == "vector-dbs"
104
+ Requires-Dist: weaviate-client>=3.0.0; extra == "vector-dbs"
105
+ Requires-Dist: qdrant-client>=1.0.0; extra == "vector-dbs"
106
+ Requires-Dist: chromadb>=0.4.0; extra == "vector-dbs"
107
+ Requires-Dist: pymilvus>=2.3.0; extra == "vector-dbs"
108
+ Requires-Dist: faiss-cpu>=1.7.0; extra == "vector-dbs"
109
+ Provides-Extra: all-providers
110
+ Requires-Dist: openai>=1.0.0; extra == "all-providers"
111
+ Requires-Dist: anthropic>=0.18.0; extra == "all-providers"
112
+ Requires-Dist: google-generativeai>=0.3.0; extra == "all-providers"
113
+ Requires-Dist: boto3>=1.28.0; extra == "all-providers"
114
+ Requires-Dist: azure-ai-openai>=1.0.0; extra == "all-providers"
115
+ Requires-Dist: cohere>=4.0.0; extra == "all-providers"
116
+ Requires-Dist: mistralai>=0.4.2; extra == "all-providers"
117
+ Requires-Dist: together>=0.2.0; extra == "all-providers"
118
+ Requires-Dist: groq>=0.4.0; extra == "all-providers"
119
+ Requires-Dist: ollama>=0.1.0; extra == "all-providers"
120
+ Requires-Dist: replicate>=0.15.0; extra == "all-providers"
121
+ Requires-Dist: langchain>=0.1.0; extra == "all-providers"
122
+ Requires-Dist: llama-index>=0.9.0; extra == "all-providers"
123
+ Requires-Dist: transformers>=4.30.0; extra == "all-providers"
124
+ Requires-Dist: litellm>=1.0.0; extra == "all-providers"
125
+ Provides-Extra: all-mcp
126
+ Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.41b0; extra == "all-mcp"
127
+ Requires-Dist: opentelemetry-instrumentation-redis>=0.41b0; extra == "all-mcp"
128
+ Requires-Dist: opentelemetry-instrumentation-pymongo>=0.41b0; extra == "all-mcp"
129
+ Requires-Dist: opentelemetry-instrumentation-psycopg2>=0.41b0; extra == "all-mcp"
130
+ Requires-Dist: opentelemetry-instrumentation-mysql>=0.41b0; extra == "all-mcp"
131
+ Requires-Dist: opentelemetry-instrumentation-kafka-python>=0.41b0; extra == "all-mcp"
132
+ Requires-Dist: pinecone>=3.0.0; extra == "all-mcp"
133
+ Requires-Dist: weaviate-client>=3.0.0; extra == "all-mcp"
134
+ Requires-Dist: qdrant-client>=1.0.0; extra == "all-mcp"
135
+ Requires-Dist: chromadb>=0.4.0; extra == "all-mcp"
136
+ Requires-Dist: pymilvus>=2.3.0; extra == "all-mcp"
137
+ Requires-Dist: faiss-cpu>=1.7.0; extra == "all-mcp"
138
+ Requires-Dist: sqlalchemy; extra == "all-mcp"
139
+ Provides-Extra: all
140
+ Requires-Dist: openai>=1.0.0; extra == "all"
141
+ Requires-Dist: anthropic>=0.18.0; extra == "all"
142
+ Requires-Dist: google-generativeai>=0.3.0; extra == "all"
143
+ Requires-Dist: boto3>=1.28.0; extra == "all"
144
+ Requires-Dist: azure-ai-openai>=1.0.0; extra == "all"
145
+ Requires-Dist: cohere>=4.0.0; extra == "all"
146
+ Requires-Dist: mistralai>=0.4.2; extra == "all"
147
+ Requires-Dist: together>=0.2.0; extra == "all"
148
+ Requires-Dist: groq>=0.4.0; extra == "all"
149
+ Requires-Dist: ollama>=0.1.0; extra == "all"
150
+ Requires-Dist: replicate>=0.15.0; extra == "all"
151
+ Requires-Dist: langchain>=0.1.0; extra == "all"
152
+ Requires-Dist: llama-index>=0.9.0; extra == "all"
153
+ Requires-Dist: transformers>=4.30.0; extra == "all"
154
+ Requires-Dist: nvidia-ml-py>=11.495.46; extra == "all"
155
+ Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.41b0; extra == "all"
156
+ Requires-Dist: opentelemetry-instrumentation-redis>=0.41b0; extra == "all"
157
+ Requires-Dist: opentelemetry-instrumentation-pymongo>=0.41b0; extra == "all"
158
+ Requires-Dist: opentelemetry-instrumentation-psycopg2>=0.41b0; extra == "all"
159
+ Requires-Dist: opentelemetry-instrumentation-mysql>=0.41b0; extra == "all"
160
+ Requires-Dist: opentelemetry-instrumentation-kafka-python>=0.41b0; extra == "all"
161
+ Requires-Dist: pinecone>=3.0.0; extra == "all"
162
+ Requires-Dist: weaviate-client>=3.0.0; extra == "all"
163
+ Requires-Dist: qdrant-client>=1.0.0; extra == "all"
164
+ Requires-Dist: chromadb>=0.4.0; extra == "all"
165
+ Requires-Dist: pymilvus>=2.3.0; extra == "all"
166
+ Requires-Dist: faiss-cpu>=1.7.0; extra == "all"
167
+ Requires-Dist: sqlalchemy; extra == "all"
168
+ Provides-Extra: dev
169
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
170
+ Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
171
+ Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
172
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
173
+ Requires-Dist: black>=23.0.0; extra == "dev"
174
+ Requires-Dist: isort>=5.12.0; extra == "dev"
175
+ Requires-Dist: pylint>=2.17.0; extra == "dev"
176
+ Requires-Dist: mypy>=1.0.0; extra == "dev"
177
+ Requires-Dist: build>=0.10.0; extra == "dev"
178
+ Requires-Dist: twine>=4.0.0; extra == "dev"
179
+ Dynamic: license-file
180
+
181
+ # GenAI OpenTelemetry Auto-Instrumentation
182
+
183
+ Production-ready OpenTelemetry instrumentation for GenAI/LLM applications with zero-code setup.
184
+
185
+ ## Features
186
+
187
+ 🚀 **Zero-Code Instrumentation** - Just install and set env vars
188
+ 🤖 **15+ LLM Providers** - OpenAI, Anthropic, Google, AWS, Azure, and more
189
+ 🔧 **MCP Tool Support** - Auto-instrument databases, APIs, caches, vector DBs
190
+ 💰 **Cost Tracking** - Automatic cost calculation per request
191
+ 🎮 **GPU Metrics** - Real-time GPU utilization, memory, temperature
192
+ 📊 **Complete Observability** - Traces, metrics, and rich span attributes
193
+ ➕ **Service Instance ID & Environment** - Identify your services and environments
194
+ ⏱️ **Configurable Exporter Timeout** - Set timeout for OTLP exporter
195
+ 🔗 **OpenInference Instrumentors** - Smolagents, MCP, and LiteLLM instrumentation
196
+
197
+ ## Quick Start
198
+
199
+ ### Installation
200
+
201
+ ```bash
202
+ pip install genai-otel-instrument
203
+ ```
204
+
205
+ ### Usage
206
+
207
+ **Option 1: Environment Variables (No code changes)**
208
+
209
+ ```bash
210
+ export OTEL_SERVICE_NAME=my-llm-app
211
+ export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
212
+ python your_app.py
213
+ ```
214
+
215
+ **Option 2: One line of code**
216
+
217
+ ```python
218
+ import genai_otel
219
+ genai_otel.instrument()
220
+
221
+ # Your existing code works unchanged
222
+ import openai
223
+ client = openai.OpenAI()
224
+ response = client.chat.completions.create(...)
225
+ ```
226
+
227
+ **Option 3: CLI wrapper**
228
+
229
+ ```bash
230
+ genai-instrument python your_app.py
231
+ ```
232
+
233
+ For a more comprehensive demonstration of various LLM providers and MCP tools, refer to `example_usage.py` in the project root. Note that running this example requires setting up relevant API keys and external services (e.g., databases, Redis, Pinecone).
234
+
235
+ ## What Gets Instrumented?
236
+
237
+ ### LLM Providers (Auto-detected)
238
+ - OpenAI, Anthropic, Google AI, AWS Bedrock, Azure OpenAI
239
+ - Cohere, Mistral AI, Together AI, Groq, Ollama
240
+ - Vertex AI, Replicate, Anyscale, HuggingFace
241
+
242
+ ### Frameworks
243
+ - LangChain (chains, agents, tools)
244
+ - LlamaIndex (query engines, indices)
245
+
246
+ ### MCP Tools (Model Context Protocol)
247
+ - **Databases**: PostgreSQL, MySQL, MongoDB, SQLAlchemy
248
+ - **Caching**: Redis
249
+ - **Message Queues**: Apache Kafka
250
+ - **Vector Databases**: Pinecone, Weaviate, Qdrant, ChromaDB, Milvus, FAISS
251
+ - **APIs**: HTTP/REST requests (requests, httpx)
252
+
253
+ ### OpenInference (Optional - Python 3.10+ only)
254
+ - Smolagents
255
+ - MCP
256
+ - LiteLLM
257
+
258
+ **Note:** OpenInference instrumentors require Python >= 3.10. Install with:
259
+ ```bash
260
+ pip install genai-otel-instrument[openinference]
261
+ ```
262
+
263
+ ## Collected Telemetry
264
+
265
+ ### Traces
266
+ Every LLM call, database query, API request, and vector search is traced with full context propagation.
267
+
268
+ ### Metrics
269
+
270
+ **GenAI Metrics:**
271
+ - `gen_ai.requests` - Request counts by provider/model
272
+ - `gen_ai.client.token.usage` - Token usage (prompt/completion)
273
+ - `gen_ai.client.operation.duration` - Request latency histogram (optimized buckets for LLM workloads)
274
+ - `gen_ai.usage.cost` - Total estimated costs in USD
275
+ - `gen_ai.usage.cost.prompt` - Prompt tokens cost (granular)
276
+ - `gen_ai.usage.cost.completion` - Completion tokens cost (granular)
277
+ - `gen_ai.usage.cost.reasoning` - Reasoning tokens cost (OpenAI o1 models)
278
+ - `gen_ai.usage.cost.cache_read` - Cache read cost (Anthropic)
279
+ - `gen_ai.usage.cost.cache_write` - Cache write cost (Anthropic)
280
+ - `gen_ai.client.errors` - Error counts by operation and type
281
+ - `gen_ai.gpu.*` - GPU utilization, memory, temperature (ObservableGauges)
282
+ - `gen_ai.co2.emissions` - CO2 emissions tracking (opt-in)
283
+ - `gen_ai.server.ttft` - Time to First Token for streaming responses (histogram, 1ms-10s buckets)
284
+ - `gen_ai.server.tbt` - Time Between Tokens for streaming responses (histogram, 10ms-2.5s buckets)
285
+
286
+ **MCP Metrics (Database Operations):**
287
+ - `mcp.requests` - Number of MCP/database requests
288
+ - `mcp.client.operation.duration` - Operation duration histogram (1ms to 10s buckets)
289
+ - `mcp.request.size` - Request payload size histogram (100B to 5MB buckets)
290
+ - `mcp.response.size` - Response payload size histogram (100B to 5MB buckets)
291
+
292
+ ### Span Attributes
293
+ **Core Attributes:**
294
+ - `gen_ai.system` - Provider name (e.g., "openai")
295
+ - `gen_ai.operation.name` - Operation type (e.g., "chat")
296
+ - `gen_ai.request.model` - Model identifier
297
+ - `gen_ai.usage.prompt_tokens` / `gen_ai.usage.input_tokens` - Input tokens (dual emission supported)
298
+ - `gen_ai.usage.completion_tokens` / `gen_ai.usage.output_tokens` - Output tokens (dual emission supported)
299
+ - `gen_ai.usage.total_tokens` - Total tokens
300
+
301
+ **Request Parameters:**
302
+ - `gen_ai.request.temperature` - Temperature setting
303
+ - `gen_ai.request.top_p` - Top-p sampling
304
+ - `gen_ai.request.max_tokens` - Max tokens requested
305
+ - `gen_ai.request.frequency_penalty` - Frequency penalty
306
+ - `gen_ai.request.presence_penalty` - Presence penalty
307
+
308
+ **Response Attributes:**
309
+ - `gen_ai.response.id` - Response ID from provider
310
+ - `gen_ai.response.model` - Actual model used (may differ from request)
311
+ - `gen_ai.response.finish_reasons` - Array of finish reasons
312
+
313
+ **Tool/Function Calls:**
314
+ - `llm.tools` - JSON-serialized tool definitions
315
+ - `llm.output_messages.{choice}.message.tool_calls.{index}.tool_call.id` - Tool call ID
316
+ - `llm.output_messages.{choice}.message.tool_calls.{index}.tool_call.function.name` - Function name
317
+ - `llm.output_messages.{choice}.message.tool_calls.{index}.tool_call.function.arguments` - Function arguments
318
+
319
+ **Cost Attributes (granular):**
320
+ - `gen_ai.usage.cost.total` - Total cost
321
+ - `gen_ai.usage.cost.prompt` - Prompt tokens cost
322
+ - `gen_ai.usage.cost.completion` - Completion tokens cost
323
+ - `gen_ai.usage.cost.reasoning` - Reasoning tokens cost (o1 models)
324
+ - `gen_ai.usage.cost.cache_read` - Cache read cost (Anthropic)
325
+ - `gen_ai.usage.cost.cache_write` - Cache write cost (Anthropic)
326
+
327
+ **Streaming Attributes:**
328
+ - `gen_ai.server.ttft` - Time to First Token (seconds) for streaming responses
329
+ - `gen_ai.streaming.token_count` - Total number of chunks/tokens in streaming response
330
+
331
+ **Content Events (opt-in):**
332
+ - `gen_ai.prompt.{index}` events with role and content
333
+ - `gen_ai.completion.{index}` events with role and content
334
+
335
+ **Additional:**
336
+ - Database, vector DB, and API attributes from MCP instrumentation
337
+
338
+ ## Configuration
339
+
340
+ ### Environment Variables
341
+
342
+ ```bash
343
+ # Required
344
+ OTEL_SERVICE_NAME=my-app
345
+ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
346
+
347
+ # Optional
348
+ OTEL_EXPORTER_OTLP_HEADERS=x-api-key=secret
349
+ GENAI_ENABLE_GPU_METRICS=true
350
+ GENAI_ENABLE_COST_TRACKING=true
351
+ GENAI_ENABLE_MCP_INSTRUMENTATION=true
352
+ GENAI_GPU_COLLECTION_INTERVAL=5 # GPU metrics collection interval in seconds (default: 5)
353
+ OTEL_SERVICE_INSTANCE_ID=instance-1 # Optional service instance id
354
+ OTEL_ENVIRONMENT=production # Optional environment
355
+ OTEL_EXPORTER_OTLP_TIMEOUT=10.0 # Optional timeout for OTLP exporter
356
+
357
+ # Semantic conventions (NEW)
358
+ OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai # "gen_ai" for new conventions only, "gen_ai/dup" for dual emission
359
+ GENAI_ENABLE_CONTENT_CAPTURE=false # WARNING: May capture sensitive data. Enable with caution.
360
+
361
+ # Logging configuration
362
+ GENAI_OTEL_LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL. Logs are written to 'logs/genai_otel.log' with rotation (10 files, 10MB each).
363
+
364
+ # Error handling
365
+ GENAI_FAIL_ON_ERROR=false # true to fail fast, false to continue on errors
366
+ ```
367
+
368
+ ### Programmatic Configuration
369
+
370
+ ```python
371
+ import genai_otel
372
+
373
+ genai_otel.instrument(
374
+ service_name="my-app",
375
+ endpoint="http://localhost:4318",
376
+ enable_gpu_metrics=True,
377
+ enable_cost_tracking=True,
378
+ enable_mcp_instrumentation=True
379
+ )
380
+ ```
381
+
382
+ ### Sample Environment File (`sample.env`)
383
+
384
+ A `sample.env` file has been generated in the project root directory. This file contains commented-out examples of all supported environment variables, along with their default values or expected formats. You can copy this file to `.env` and uncomment/modify the variables to configure the instrumentation for your specific needs.
385
+
386
+ ## Example: Full-Stack GenAI App
387
+
388
+ ```python
389
+ import genai_otel
390
+ genai_otel.instrument()
391
+
392
+ import openai
393
+ import pinecone
394
+ import redis
395
+ import psycopg2
396
+
397
+ # All of these are automatically instrumented:
398
+
399
+ # Cache check
400
+ cache = redis.Redis().get('key')
401
+
402
+ # Vector search
403
+ pinecone_index = pinecone.Index("embeddings")
404
+ results = pinecone_index.query(vector=[...], top_k=5)
405
+
406
+ # Database query
407
+ conn = psycopg2.connect("dbname=mydb")
408
+ cursor = conn.cursor()
409
+ cursor.execute("SELECT * FROM context")
410
+
411
+ # LLM call with full context
412
+ client = openai.OpenAI()
413
+ response = client.chat.completions.create(
414
+ model="gpt-4",
415
+ messages=[...]
416
+ )
417
+
418
+ # You get:
419
+ # ✓ Distributed traces across all services
420
+ # ✓ Cost tracking for the LLM call
421
+ # ✓ Performance metrics for DB, cache, vector DB
422
+ # ✓ GPU metrics if using local models
423
+ # ✓ Complete observability with zero manual instrumentation
424
+ ```
425
+
426
+ ## Backend Integration
427
+
428
+ Works with any OpenTelemetry-compatible backend:
429
+ - Jaeger, Zipkin
430
+ - Prometheus, Grafana
431
+ - Datadog, New Relic, Honeycomb
432
+ - AWS X-Ray, Google Cloud Trace
433
+ - Elastic APM, Splunk
434
+ - Self-hosted OTEL Collector
435
+
436
+ ## Project Structure
437
+
438
+ ```bash
439
+ genai-otel-instrument/
440
+ ├── setup.py
441
+ ├── MANIFEST.in
442
+ ├── README.md
443
+ ├── LICENSE
444
+ ├── example_usage.py
445
+ └── genai_otel/
446
+ ├── __init__.py
447
+ ├── config.py
448
+ ├── auto_instrument.py
449
+ ├── cli.py
450
+ ├── cost_calculator.py
451
+ ├── gpu_metrics.py
452
+ ├── instrumentors/
453
+ │ ├── __init__.py
454
+ │ ├── base.py
455
+ │ └── (other instrumentor files)
456
+ └── mcp_instrumentors/
457
+ ├── __init__.py
458
+ ├── manager.py
459
+ └── (other mcp files)
460
+ ```
461
+
462
+ ## License
463
+ Apache-2.0 license
@@ -0,0 +1,44 @@
1
+ genai_otel/__init__.py,sha256=OWgm1dihRkwBQU8fUPnVhE5XCZeF5f15UyH4w6LqGZU,4469
2
+ genai_otel/__version__.py,sha256=zZ8gTCIyqP1ayOMOGPrtjRAYol1rcsahyb0_47c1grk,751
3
+ genai_otel/auto_instrument.py,sha256=bLOR_9y2gSB4VfwRrYI7YX_et-NwrpIzbOnmkNqbDHE,15343
4
+ genai_otel/cli.py,sha256=mbhaTU0WIAkvPKdIing-guIxPDjEKQftChWQUtPFzkY,3170
5
+ genai_otel/config.py,sha256=GSJZApBNKKXm5rp5jQsDk91qcHYzCrhmf06DHbpZMBE,6685
6
+ genai_otel/cost_calculator.py,sha256=Jlp-UPO8vcfWy5u46ib1I_6w0bvVrMsz1kWi1Vn6QX4,10588
7
+ genai_otel/exceptions.py,sha256=gIRvbI7c4V-M-PG9jS0o4ESRwHUWCm6DVihjfyJI1yg,429
8
+ genai_otel/gpu_metrics.py,sha256=MLQTyeGwd8Zxwev_iUddl91lfj2me6CPMOjGRnxM2Cs,9754
9
+ genai_otel/llm_pricing.json,sha256=fFajtjXvcNfuz_JOblz4BXpiliZvtL1Fybpa9hJv-v4,17733
10
+ genai_otel/logging_config.py,sha256=XSBeslTqeHUBBadKJV2W8JFIOXorEVZ6W0xqNKjiPlA,1463
11
+ genai_otel/metrics.py,sha256=Vngwtc1MAMAE7JVpbT_KfiCQ5TdIAKIs_0oztjJdDTg,2671
12
+ genai_otel/py.typed,sha256=oe-lun16QtsTO6qa3gicjgj_F4jU7LSKCnBYLr6P5Yk,88
13
+ genai_otel/instrumentors/__init__.py,sha256=39CQZZS-AcHNn37pdt1rCOVBvX9t5RGMPY3sEulQzMA,1821
14
+ genai_otel/instrumentors/anthropic_instrumentor.py,sha256=3koeXSJccALdZiRibavwQt8_lrXYwEhdWfA3dnCo_ng,4837
15
+ genai_otel/instrumentors/anyscale_instrumentor.py,sha256=WUcQVDK8W76gkrAT_TLgzFd7NY42Rn6x0irT7VV2bbI,774
16
+ genai_otel/instrumentors/aws_bedrock_instrumentor.py,sha256=W469XxNVsb6eDjerk3SkjZFZEOIzH_HkBkmqqSCRBhU,3670
17
+ genai_otel/instrumentors/azure_openai_instrumentor.py,sha256=HumsAAtW9YzbcyBCrIGhE5KvZ6-mxSbsEoI_W0JU7xg,2428
18
+ genai_otel/instrumentors/base.py,sha256=Xke8H3WeLLW6kyKX3z3WC6A34dnOagWGgiIuicZ-rqs,24219
19
+ genai_otel/instrumentors/cohere_instrumentor.py,sha256=gFypgFH-xm-Aao03vLcRCGklylBGZt0F0n2y9_HgkFo,2442
20
+ genai_otel/instrumentors/google_ai_instrumentor.py,sha256=ExNo0_OxfCxaRpuUXYU8UZ-ClQRHRLUvf7-kMC6zdc8,2984
21
+ genai_otel/instrumentors/groq_instrumentor.py,sha256=bCm7IDmDyvg0-XuzcCSO5xf9QvDlQGwb7bdQ_ooS6QI,3398
22
+ genai_otel/instrumentors/huggingface_instrumentor.py,sha256=parX4Vm0fgrzf2H2mpIMs24oRpM6bCQpCqfW3B_ilC4,3558
23
+ genai_otel/instrumentors/langchain_instrumentor.py,sha256=1Y_zGBQcUNrh877k146XOW4wLBXBkNtbyuEkORXFIyQ,2760
24
+ genai_otel/instrumentors/llamaindex_instrumentor.py,sha256=zZ1J7W4yQo1Ur6Y5y0UXpDdEx9oDnmsqNIin5Jrv9os,1206
25
+ genai_otel/instrumentors/mistralai_instrumentor.py,sha256=6KGgC_GeJagP-hYQjCBGcgahteZpWhF9RxmlITfq2Bs,4807
26
+ genai_otel/instrumentors/ollama_instrumentor.py,sha256=gS_2YW0mEo_wg82vglQR0HuZ0NCmCU0JKQ90kw6f5kk,2875
27
+ genai_otel/instrumentors/openai_instrumentor.py,sha256=0q2vml2oWnTRzfVTEP0_njfxqZS8b3Qek-apeecXvvs,9263
28
+ genai_otel/instrumentors/replicate_instrumentor.py,sha256=7Jk0yTlmM2-sJpkfozA9LVB52fXKYV3tLhAvWSLvn58,1270
29
+ genai_otel/instrumentors/togetherai_instrumentor.py,sha256=iFounG9OtJXyN3oxk9_k_XKmtC_WUtnUxN4d_IxIomY,1324
30
+ genai_otel/instrumentors/vertexai_instrumentor.py,sha256=aphjvokd82mlyA738WUqGojT88OIFd85u4z2kHnBqrE,1453
31
+ genai_otel/mcp_instrumentors/__init__.py,sha256=0yVx5bwFxCmI72BORDKLgkn0t5h_xRXvtjUskVE60eo,512
32
+ genai_otel/mcp_instrumentors/api_instrumentor.py,sha256=tAogtajeq4zjaM4-05XYSOzD3ig2mXX9_xFyGHL4auQ,5690
33
+ genai_otel/mcp_instrumentors/base.py,sha256=oF_GyGZPEDS-NapIYzM_-TV1KYJeVlXXFzxzs9sMsqU,4044
34
+ genai_otel/mcp_instrumentors/database_instrumentor.py,sha256=zjyIIme81--WYe7q8FwxYsDhjUcXaNoLZj7tqmuAX-8,13256
35
+ genai_otel/mcp_instrumentors/kafka_instrumentor.py,sha256=QJYJC1rvo_zZAIaw-cp_IcpG-EhUqkCfZ4TIZzZ2hK8,987
36
+ genai_otel/mcp_instrumentors/manager.py,sha256=1Pj5lkEOL8Yq1Oeud4ZExN6k6NLIVtTzKnFLNiFdJvw,5895
37
+ genai_otel/mcp_instrumentors/redis_instrumentor.py,sha256=KUbs0dMyfMzU4T0SS8u43I5fvr09lcBBM92I3KCsYUw,943
38
+ genai_otel/mcp_instrumentors/vector_db_instrumentor.py,sha256=2vhnk4PGpfYKr-XlRbnCIOap4BPKHOn--fh-ai2YXlM,9994
39
+ genai_otel_instrument-0.1.1.dev0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
40
+ genai_otel_instrument-0.1.1.dev0.dist-info/METADATA,sha256=NMd0W0AbdmVc5seUf_trkhlFimd5UVq_F1XxeNd7YBk,19215
41
+ genai_otel_instrument-0.1.1.dev0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
42
+ genai_otel_instrument-0.1.1.dev0.dist-info/entry_points.txt,sha256=E9UqoHA_fq69yNGAY3SRYf5HH94sZT5DiDueiU1v0KM,57
43
+ genai_otel_instrument-0.1.1.dev0.dist-info/top_level.txt,sha256=cvCm8PUwvYUSQKruk-x6S-_YuDyhOBk8gD910XICcbg,11
44
+ genai_otel_instrument-0.1.1.dev0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (80.9.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ genai-instrument = genai_otel.cli:main