metergraph 0.6.9__tar.gz → 0.6.11__tar.gz
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.
- {metergraph-0.6.9 → metergraph-0.6.11}/PKG-INFO +62 -13
- metergraph-0.6.9/src/metergraph.egg-info/PKG-INFO → metergraph-0.6.11/README.md +54 -32
- metergraph-0.6.11/pyproject.toml +49 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/__init__.py +19 -4
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_capture.py +208 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_genai_attrs.py +185 -4
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_version.py +1 -1
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/opentelemetry.py +8 -1
- metergraph-0.6.9/README.md → metergraph-0.6.11/src/metergraph.egg-info/PKG-INFO +81 -7
- metergraph-0.6.9/pyproject.toml +0 -34
- {metergraph-0.6.9 → metergraph-0.6.11}/MANIFEST.in +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/setup.cfg +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_batch_first.py +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_config.py +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_context.py +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_failure_log.py +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_gateway.py +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_provider_batch.py +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_repo_config.py +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_session.py +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_template.py +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_tool_definitions.py +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_track.py +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_transport.py +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph.egg-info/SOURCES.txt +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph.egg-info/dependency_links.txt +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph.egg-info/requires.txt +0 -0
- {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph.egg-info/top_level.txt +0 -0
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: metergraph
|
|
3
|
-
Version: 0.6.
|
|
4
|
-
Summary:
|
|
5
|
-
Author:
|
|
3
|
+
Version: 0.6.11
|
|
4
|
+
Summary: Zero-dependency Python SDK for function-level LLM cost attribution across major LLM providers and gateways, including OpenAI, Anthropic, Gemini, and Vercel AI Gateway.
|
|
5
|
+
Author: Metergraph
|
|
6
6
|
License-Expression: Apache-2.0
|
|
7
7
|
Project-URL: Homepage, https://www.metergraph.dev/
|
|
8
|
-
Project-URL:
|
|
9
|
-
Project-URL:
|
|
10
|
-
|
|
8
|
+
Project-URL: Documentation, https://github.com/metergraph/metergraphsdk/tree/main/python#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/metergraph/metergraphsdk
|
|
10
|
+
Project-URL: Issues, https://github.com/metergraph/metergraphsdk/issues
|
|
11
|
+
Project-URL: Release notes, https://github.com/metergraph/metergraphsdk/releases
|
|
12
|
+
Keywords: llm,llm-cost,llm-observability,cost-attribution,ai-agents,openai,anthropic,gemini,vercel-ai-sdk,vercel-ai-gateway,opentelemetry,self-hosted
|
|
11
13
|
Classifier: Intended Audience :: Developers
|
|
12
14
|
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
13
15
|
Classifier: Typing :: Typed
|
|
@@ -25,8 +27,18 @@ Requires-Dist: opentelemetry-sdk>=1.30; extra == "dev"
|
|
|
25
27
|
|
|
26
28
|
# metergraph (Python)
|
|
27
29
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
+
See where your agentic AI application's LLM spend comes from. Attribute usage
|
|
31
|
+
to functions, agents, and workflows without changing provider call sites, then
|
|
32
|
+
send it to Metergraph Cloud or your self-hosted Metergraph server.
|
|
33
|
+
|
|
34
|
+
[Metergraph](https://www.metergraph.dev/) helps teams understand and optimize
|
|
35
|
+
agentic AI applications. This open-source, zero-runtime-dependency package
|
|
36
|
+
provides function-level LLM cost attribution for OpenAI, Anthropic, Gemini, and
|
|
37
|
+
Python Vercel AI Gateway clients. Paid Metergraph builds on that attribution
|
|
38
|
+
with experimentation and optimization across models, prompts, tools,
|
|
39
|
+
retrieval, context, batching, and caching. This package captures and
|
|
40
|
+
attributes usage; it does not run experiments or optimize your application.
|
|
41
|
+
|
|
30
42
|
Initialize Metergraph once, then wrap each provider client. `init()` reads the
|
|
31
43
|
token and other omitted options from the environment.
|
|
32
44
|
|
|
@@ -103,7 +115,7 @@ OpenRouter is captured the same way: point an OpenAI client at
|
|
|
103
115
|
`reported_cost_usd` to Chat Completions rows without changing the requested model
|
|
104
116
|
or the capture provider. A trusted custom domain uses
|
|
105
117
|
`metergraph.wrap(client, gateway="openrouter")`. The runnable
|
|
106
|
-
[Python OpenRouter example](../examples/
|
|
118
|
+
[Python OpenRouter example](../examples/integrations/providers/openrouter/python/) covers requested-vs-
|
|
107
119
|
served model, reported-vs-catalog cost, streaming usage, and the BYOK limitation.
|
|
108
120
|
|
|
109
121
|
## OpenTelemetry GenAI export
|
|
@@ -125,17 +137,40 @@ from metergraph.opentelemetry import MetergraphGenAIExporter
|
|
|
125
137
|
|
|
126
138
|
litellm.callbacks.append(OpenTelemetry(OpenTelemetryConfig(
|
|
127
139
|
exporter=MetergraphGenAIExporter(),
|
|
128
|
-
capture_message_content="SPAN_ONLY",
|
|
129
140
|
)))
|
|
141
|
+
|
|
142
|
+
response = litellm.completion(
|
|
143
|
+
model="openai/gpt-5-mini",
|
|
144
|
+
messages=messages,
|
|
145
|
+
metadata={"generation_name": "ticket-triage"},
|
|
146
|
+
)
|
|
130
147
|
```
|
|
131
148
|
|
|
149
|
+
- LiteLLM logs message content on its spans by default. Releases before 1.85
|
|
150
|
+
have no `capture_message_content` option, so leave it out.
|
|
151
|
+
- Do not set `litellm.turn_off_message_logging`. It removes messages, tool
|
|
152
|
+
definitions and outputs from the spans, so MeterGraph can count the calls but
|
|
153
|
+
cannot analyse them.
|
|
154
|
+
- Name each call with `metadata={"generation_name": "<workload name>"}`.
|
|
155
|
+
LiteLLM uses it as the span name and MeterGraph records it as the call's
|
|
156
|
+
route. Without it every call is stored under the route `chat`. A
|
|
157
|
+
`metergraph.route` or `gen_ai.prompt.name` span attribute still takes
|
|
158
|
+
precedence.
|
|
159
|
+
- To group the calls of a multi-step agent run into one trace, make them inside
|
|
160
|
+
one application span and set `USE_OTEL_LITELLM_REQUEST_SPAN=true`. Without
|
|
161
|
+
that variable LiteLLM writes each call onto the application span itself, and
|
|
162
|
+
only one of the calls is recorded.
|
|
163
|
+
- Pass a new `metadata` dict to each call. Reusing one dict across calls makes
|
|
164
|
+
LiteLLM 1.103 drop spans.
|
|
165
|
+
|
|
132
166
|
The exporter preserves OpenTelemetry trace identity, model/provider metadata,
|
|
133
167
|
token usage, latency, system instructions, ordered messages, and text output.
|
|
134
|
-
|
|
168
|
+
From LiteLLM spans it also records the provider response id as the request id,
|
|
169
|
+
the request's tool definitions, and the tool calls in the response. Text parts
|
|
135
170
|
are retained and replayable in the current POC pipeline. Calls containing other
|
|
136
171
|
part types retain their model, usage, timing, and status metadata, but those
|
|
137
172
|
parts are not replayable yet. See the runnable
|
|
138
|
-
[`
|
|
173
|
+
[`LiteLLM OpenTelemetry example`](../examples/integrations/telemetry/litellm/python/).
|
|
139
174
|
|
|
140
175
|
The exporter reads the OpenTelemetry `gen_ai.*` conventions, OpenInference
|
|
141
176
|
(Arize Phoenix), Langfuse and LangSmith spans. Dialects that label span kind
|
|
@@ -212,6 +247,20 @@ message batches are captured per inference while iterating a wrapped
|
|
|
212
247
|
rows carry real per-result usage and the batch pricing flag; job-management
|
|
213
248
|
polls themselves are not miscounted as model calls.
|
|
214
249
|
|
|
250
|
+
OpenAI Responses created with `background=True` are recorded once, when a
|
|
251
|
+
wrapped `client.responses.retrieve()` or `cancel()` first returns a terminal
|
|
252
|
+
status (`completed`, `failed`, `cancelled` or `incomplete`), with that
|
|
253
|
+
response's usage and output. Polls that still report `queued` or
|
|
254
|
+
`in_progress` add no rows, and latency runs from `create` to the observed
|
|
255
|
+
terminal response. A background response whose terminal status the process
|
|
256
|
+
never observes is recorded at `shutdown()` with status `abandoned` and
|
|
257
|
+
unknown usage, never as a completed call with zero tokens. A streamed
|
|
258
|
+
`retrieve(..., stream=True)` or `responses.stream(response_id=...)` resume is
|
|
259
|
+
observed through its terminal response event. Only retrieves made through the same wrapped client in the same process
|
|
260
|
+
are observed: a client derived with `with_options()` or `copy()`,
|
|
261
|
+
`with_raw_response`/`with_streaming_response` retrieves, and polling from a
|
|
262
|
+
different process leave the call to be recorded as `abandoned`.
|
|
263
|
+
|
|
215
264
|
## Batch-first execution (opt-in)
|
|
216
265
|
|
|
217
266
|
`metergraph.batch_first()` is a separate, explicitly opt-in code path from `wrap()`/capture: submit one request through a provider's Batch API, wait up to a caller-chosen deadline, and fall back to exactly one direct call if the batch hasn't finished in time. It is synchronous/blocking, matching this SDK's own background-work model — a daemon thread, not asyncio.
|
|
@@ -248,7 +297,7 @@ codebase you want instrumented:
|
|
|
248
297
|
|
|
249
298
|
```text
|
|
250
299
|
Instrument this codebase's LLM API costs with the `metergraph` PyPI package
|
|
251
|
-
(https://github.com/
|
|
300
|
+
(https://github.com/metergraph/metergraphsdk): pip install metergraph,
|
|
252
301
|
then wrap every OpenAI()/AsyncOpenAI(), Anthropic()/AsyncAnthropic(), and
|
|
253
302
|
genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
|
|
254
303
|
OpenAI or Anthropic clients pointed at https://ai-gateway.vercel.sh are Vercel
|
|
@@ -1,32 +1,17 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: metergraph
|
|
3
|
-
Version: 0.6.9
|
|
4
|
-
Summary: Fire-and-forget LLM spend capture for Metergraph
|
|
5
|
-
Author: Pioneer Square Labs
|
|
6
|
-
License-Expression: Apache-2.0
|
|
7
|
-
Project-URL: Homepage, https://www.metergraph.dev/
|
|
8
|
-
Project-URL: Repository, https://github.com/PioneerSquareLabs/metergraphsdk
|
|
9
|
-
Project-URL: Issues, https://github.com/PioneerSquareLabs/metergraphsdk/issues
|
|
10
|
-
Keywords: llm,observability,openai,anthropic,gemini,vercel-ai-gateway,cost-tracking
|
|
11
|
-
Classifier: Intended Audience :: Developers
|
|
12
|
-
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
13
|
-
Classifier: Typing :: Typed
|
|
14
|
-
Requires-Python: >=3.10
|
|
15
|
-
Description-Content-Type: text/markdown
|
|
16
|
-
Provides-Extra: otel
|
|
17
|
-
Requires-Dist: opentelemetry-sdk>=1.30; extra == "otel"
|
|
18
|
-
Provides-Extra: dev
|
|
19
|
-
Requires-Dist: build>=1; extra == "dev"
|
|
20
|
-
Requires-Dist: pytest>=8; extra == "dev"
|
|
21
|
-
Requires-Dist: openai<3,>=2.50.0; extra == "dev"
|
|
22
|
-
Requires-Dist: anthropic<1,>=0.40; extra == "dev"
|
|
23
|
-
Requires-Dist: google-genai>=1; extra == "dev"
|
|
24
|
-
Requires-Dist: opentelemetry-sdk>=1.30; extra == "dev"
|
|
25
|
-
|
|
26
1
|
# metergraph (Python)
|
|
27
2
|
|
|
28
|
-
|
|
29
|
-
|
|
3
|
+
See where your agentic AI application's LLM spend comes from. Attribute usage
|
|
4
|
+
to functions, agents, and workflows without changing provider call sites, then
|
|
5
|
+
send it to Metergraph Cloud or your self-hosted Metergraph server.
|
|
6
|
+
|
|
7
|
+
[Metergraph](https://www.metergraph.dev/) helps teams understand and optimize
|
|
8
|
+
agentic AI applications. This open-source, zero-runtime-dependency package
|
|
9
|
+
provides function-level LLM cost attribution for OpenAI, Anthropic, Gemini, and
|
|
10
|
+
Python Vercel AI Gateway clients. Paid Metergraph builds on that attribution
|
|
11
|
+
with experimentation and optimization across models, prompts, tools,
|
|
12
|
+
retrieval, context, batching, and caching. This package captures and
|
|
13
|
+
attributes usage; it does not run experiments or optimize your application.
|
|
14
|
+
|
|
30
15
|
Initialize Metergraph once, then wrap each provider client. `init()` reads the
|
|
31
16
|
token and other omitted options from the environment.
|
|
32
17
|
|
|
@@ -103,7 +88,7 @@ OpenRouter is captured the same way: point an OpenAI client at
|
|
|
103
88
|
`reported_cost_usd` to Chat Completions rows without changing the requested model
|
|
104
89
|
or the capture provider. A trusted custom domain uses
|
|
105
90
|
`metergraph.wrap(client, gateway="openrouter")`. The runnable
|
|
106
|
-
[Python OpenRouter example](../examples/
|
|
91
|
+
[Python OpenRouter example](../examples/integrations/providers/openrouter/python/) covers requested-vs-
|
|
107
92
|
served model, reported-vs-catalog cost, streaming usage, and the BYOK limitation.
|
|
108
93
|
|
|
109
94
|
## OpenTelemetry GenAI export
|
|
@@ -125,17 +110,40 @@ from metergraph.opentelemetry import MetergraphGenAIExporter
|
|
|
125
110
|
|
|
126
111
|
litellm.callbacks.append(OpenTelemetry(OpenTelemetryConfig(
|
|
127
112
|
exporter=MetergraphGenAIExporter(),
|
|
128
|
-
capture_message_content="SPAN_ONLY",
|
|
129
113
|
)))
|
|
114
|
+
|
|
115
|
+
response = litellm.completion(
|
|
116
|
+
model="openai/gpt-5-mini",
|
|
117
|
+
messages=messages,
|
|
118
|
+
metadata={"generation_name": "ticket-triage"},
|
|
119
|
+
)
|
|
130
120
|
```
|
|
131
121
|
|
|
122
|
+
- LiteLLM logs message content on its spans by default. Releases before 1.85
|
|
123
|
+
have no `capture_message_content` option, so leave it out.
|
|
124
|
+
- Do not set `litellm.turn_off_message_logging`. It removes messages, tool
|
|
125
|
+
definitions and outputs from the spans, so MeterGraph can count the calls but
|
|
126
|
+
cannot analyse them.
|
|
127
|
+
- Name each call with `metadata={"generation_name": "<workload name>"}`.
|
|
128
|
+
LiteLLM uses it as the span name and MeterGraph records it as the call's
|
|
129
|
+
route. Without it every call is stored under the route `chat`. A
|
|
130
|
+
`metergraph.route` or `gen_ai.prompt.name` span attribute still takes
|
|
131
|
+
precedence.
|
|
132
|
+
- To group the calls of a multi-step agent run into one trace, make them inside
|
|
133
|
+
one application span and set `USE_OTEL_LITELLM_REQUEST_SPAN=true`. Without
|
|
134
|
+
that variable LiteLLM writes each call onto the application span itself, and
|
|
135
|
+
only one of the calls is recorded.
|
|
136
|
+
- Pass a new `metadata` dict to each call. Reusing one dict across calls makes
|
|
137
|
+
LiteLLM 1.103 drop spans.
|
|
138
|
+
|
|
132
139
|
The exporter preserves OpenTelemetry trace identity, model/provider metadata,
|
|
133
140
|
token usage, latency, system instructions, ordered messages, and text output.
|
|
134
|
-
|
|
141
|
+
From LiteLLM spans it also records the provider response id as the request id,
|
|
142
|
+
the request's tool definitions, and the tool calls in the response. Text parts
|
|
135
143
|
are retained and replayable in the current POC pipeline. Calls containing other
|
|
136
144
|
part types retain their model, usage, timing, and status metadata, but those
|
|
137
145
|
parts are not replayable yet. See the runnable
|
|
138
|
-
[`
|
|
146
|
+
[`LiteLLM OpenTelemetry example`](../examples/integrations/telemetry/litellm/python/).
|
|
139
147
|
|
|
140
148
|
The exporter reads the OpenTelemetry `gen_ai.*` conventions, OpenInference
|
|
141
149
|
(Arize Phoenix), Langfuse and LangSmith spans. Dialects that label span kind
|
|
@@ -212,6 +220,20 @@ message batches are captured per inference while iterating a wrapped
|
|
|
212
220
|
rows carry real per-result usage and the batch pricing flag; job-management
|
|
213
221
|
polls themselves are not miscounted as model calls.
|
|
214
222
|
|
|
223
|
+
OpenAI Responses created with `background=True` are recorded once, when a
|
|
224
|
+
wrapped `client.responses.retrieve()` or `cancel()` first returns a terminal
|
|
225
|
+
status (`completed`, `failed`, `cancelled` or `incomplete`), with that
|
|
226
|
+
response's usage and output. Polls that still report `queued` or
|
|
227
|
+
`in_progress` add no rows, and latency runs from `create` to the observed
|
|
228
|
+
terminal response. A background response whose terminal status the process
|
|
229
|
+
never observes is recorded at `shutdown()` with status `abandoned` and
|
|
230
|
+
unknown usage, never as a completed call with zero tokens. A streamed
|
|
231
|
+
`retrieve(..., stream=True)` or `responses.stream(response_id=...)` resume is
|
|
232
|
+
observed through its terminal response event. Only retrieves made through the same wrapped client in the same process
|
|
233
|
+
are observed: a client derived with `with_options()` or `copy()`,
|
|
234
|
+
`with_raw_response`/`with_streaming_response` retrieves, and polling from a
|
|
235
|
+
different process leave the call to be recorded as `abandoned`.
|
|
236
|
+
|
|
215
237
|
## Batch-first execution (opt-in)
|
|
216
238
|
|
|
217
239
|
`metergraph.batch_first()` is a separate, explicitly opt-in code path from `wrap()`/capture: submit one request through a provider's Batch API, wait up to a caller-chosen deadline, and fall back to exactly one direct call if the batch hasn't finished in time. It is synchronous/blocking, matching this SDK's own background-work model — a daemon thread, not asyncio.
|
|
@@ -248,7 +270,7 @@ codebase you want instrumented:
|
|
|
248
270
|
|
|
249
271
|
```text
|
|
250
272
|
Instrument this codebase's LLM API costs with the `metergraph` PyPI package
|
|
251
|
-
(https://github.com/
|
|
273
|
+
(https://github.com/metergraph/metergraphsdk): pip install metergraph,
|
|
252
274
|
then wrap every OpenAI()/AsyncOpenAI(), Anthropic()/AsyncAnthropic(), and
|
|
253
275
|
genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
|
|
254
276
|
OpenAI or Anthropic clients pointed at https://ai-gateway.vercel.sh are Vercel
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "metergraph"
|
|
3
|
+
version = "0.6.11"
|
|
4
|
+
description = "Zero-dependency Python SDK for function-level LLM cost attribution across major LLM providers and gateways, including OpenAI, Anthropic, Gemini, and Vercel AI Gateway."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.10"
|
|
7
|
+
license = "Apache-2.0"
|
|
8
|
+
authors = [{ name = "Metergraph" }]
|
|
9
|
+
keywords = [
|
|
10
|
+
"llm",
|
|
11
|
+
"llm-cost",
|
|
12
|
+
"llm-observability",
|
|
13
|
+
"cost-attribution",
|
|
14
|
+
"ai-agents",
|
|
15
|
+
"openai",
|
|
16
|
+
"anthropic",
|
|
17
|
+
"gemini",
|
|
18
|
+
"vercel-ai-sdk",
|
|
19
|
+
"vercel-ai-gateway",
|
|
20
|
+
"opentelemetry",
|
|
21
|
+
"self-hosted",
|
|
22
|
+
]
|
|
23
|
+
classifiers = [
|
|
24
|
+
"Intended Audience :: Developers",
|
|
25
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
26
|
+
"Typing :: Typed",
|
|
27
|
+
]
|
|
28
|
+
dependencies = []
|
|
29
|
+
|
|
30
|
+
[project.urls]
|
|
31
|
+
Homepage = "https://www.metergraph.dev/"
|
|
32
|
+
Documentation = "https://github.com/metergraph/metergraphsdk/tree/main/python#readme"
|
|
33
|
+
Repository = "https://github.com/metergraph/metergraphsdk"
|
|
34
|
+
Issues = "https://github.com/metergraph/metergraphsdk/issues"
|
|
35
|
+
"Release notes" = "https://github.com/metergraph/metergraphsdk/releases"
|
|
36
|
+
|
|
37
|
+
[project.optional-dependencies]
|
|
38
|
+
otel = ["opentelemetry-sdk>=1.30"]
|
|
39
|
+
dev = ["build>=1", "pytest>=8", "openai>=2.50.0,<3", "anthropic>=0.40,<1", "google-genai>=1", "opentelemetry-sdk>=1.30"]
|
|
40
|
+
|
|
41
|
+
[build-system]
|
|
42
|
+
requires = ["setuptools>=68"]
|
|
43
|
+
build-backend = "setuptools.build_meta"
|
|
44
|
+
|
|
45
|
+
[tool.setuptools.packages.find]
|
|
46
|
+
where = ["src"]
|
|
47
|
+
|
|
48
|
+
[tool.pytest.ini_options]
|
|
49
|
+
testpaths = ["tests"]
|
|
@@ -10,7 +10,13 @@ import uuid
|
|
|
10
10
|
from datetime import datetime, timezone
|
|
11
11
|
from typing import Any, Callable
|
|
12
12
|
|
|
13
|
-
from ._capture import
|
|
13
|
+
from ._capture import (
|
|
14
|
+
DEFAULT_TEXT_MAX_BYTES,
|
|
15
|
+
Options,
|
|
16
|
+
Runtime,
|
|
17
|
+
set_runtime,
|
|
18
|
+
)
|
|
19
|
+
from ._capture import finish_background_calls as _finish_background_calls
|
|
14
20
|
from ._capture import wrap as _wrap
|
|
15
21
|
from ._config import ConfigPoller
|
|
16
22
|
from ._context import (
|
|
@@ -114,9 +120,12 @@ def init(
|
|
|
114
120
|
if repo_config is None and not _warned_no_repository:
|
|
115
121
|
_warned_no_repository = True
|
|
116
122
|
log.warning(
|
|
117
|
-
"Metergraph
|
|
118
|
-
"
|
|
119
|
-
"
|
|
123
|
+
"Metergraph is capturing calls normally. Repository identity is "
|
|
124
|
+
"optional and not set, so traces are not linked to a source "
|
|
125
|
+
"repository. To link them, commit .metergraph/config.json "
|
|
126
|
+
'containing {"repository": "owner/name"}, set '
|
|
127
|
+
"METERGRAPH_REPOSITORY=owner/name, pass init(repository='owner/name'), "
|
|
128
|
+
"or run `metergraph setup` in the project."
|
|
120
129
|
)
|
|
121
130
|
session = (
|
|
122
131
|
SessionManager(
|
|
@@ -289,6 +298,12 @@ def flush(timeout: float = 3.0) -> bool:
|
|
|
289
298
|
|
|
290
299
|
def shutdown() -> None:
|
|
291
300
|
global _writer, _config, _session_manager
|
|
301
|
+
# Background responses whose final result was never retrieved are
|
|
302
|
+
# recorded as abandoned before the writer drains, never as zero usage.
|
|
303
|
+
try:
|
|
304
|
+
_finish_background_calls()
|
|
305
|
+
except Exception:
|
|
306
|
+
pass
|
|
292
307
|
if _config:
|
|
293
308
|
_config.stop()
|
|
294
309
|
_config = None
|
|
@@ -11,7 +11,9 @@ import os
|
|
|
11
11
|
import platform
|
|
12
12
|
import secrets
|
|
13
13
|
import sys
|
|
14
|
+
import threading
|
|
14
15
|
import time
|
|
16
|
+
from collections import OrderedDict
|
|
15
17
|
from dataclasses import dataclass
|
|
16
18
|
from datetime import datetime, timezone
|
|
17
19
|
from pathlib import Path
|
|
@@ -1693,6 +1695,11 @@ def _patch(
|
|
|
1693
1695
|
runtime = _runtime
|
|
1694
1696
|
if runtime is None:
|
|
1695
1697
|
return original(*args, **kwargs)
|
|
1698
|
+
if endpoint == "responses.stream" and kwargs.get("response_id") is not None:
|
|
1699
|
+
# Resuming an existing (background) response is not a new model
|
|
1700
|
+
# call: it retrieves with stream=True, and the retrieve observer
|
|
1701
|
+
# records the held create once from its terminal event.
|
|
1702
|
+
return original(*args, **kwargs)
|
|
1696
1703
|
if (
|
|
1697
1704
|
provider == "openai"
|
|
1698
1705
|
and endpoint == "chat.completions"
|
|
@@ -1756,6 +1763,194 @@ def _safe_finish(call: CallState, response: Any = None, **kwargs: Any) -> None:
|
|
|
1756
1763
|
pass
|
|
1757
1764
|
|
|
1758
1765
|
|
|
1766
|
+
# Background Responses (``background=True``) return a queued or in-progress
|
|
1767
|
+
# response from ``create``; output and usage arrive on a later ``retrieve`` or
|
|
1768
|
+
# ``cancel``. The capture is held until the client observes a terminal status,
|
|
1769
|
+
# then recorded once from that response. A held call the client never sees
|
|
1770
|
+
# finish is recorded as ``abandoned`` at shutdown (or when the bound is
|
|
1771
|
+
# exceeded), so it is never stored as a completed call with zero usage.
|
|
1772
|
+
_BACKGROUND_PENDING_STATUSES = frozenset({"queued", "in_progress"})
|
|
1773
|
+
_BACKGROUND_TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled", "incomplete"})
|
|
1774
|
+
_BACKGROUND_MAX_PENDING = 1024
|
|
1775
|
+
_background_lock = threading.Lock()
|
|
1776
|
+
_background: "OrderedDict[str, tuple[CallState, Any]]" = OrderedDict()
|
|
1777
|
+
|
|
1778
|
+
|
|
1779
|
+
def _clear_background_after_fork() -> None:
|
|
1780
|
+
# Held calls belong to the parent; the child must not record them again.
|
|
1781
|
+
global _background_lock
|
|
1782
|
+
_background_lock = threading.Lock()
|
|
1783
|
+
_background.clear()
|
|
1784
|
+
|
|
1785
|
+
|
|
1786
|
+
if hasattr(os, "register_at_fork"):
|
|
1787
|
+
os.register_at_fork(after_in_child=_clear_background_after_fork)
|
|
1788
|
+
|
|
1789
|
+
|
|
1790
|
+
def _hold_background(call: CallState, response: Any) -> bool:
|
|
1791
|
+
response_id = _get(response, "id")
|
|
1792
|
+
if not isinstance(response_id, str) or not response_id:
|
|
1793
|
+
return False
|
|
1794
|
+
evicted: list[tuple[CallState, Any]] = []
|
|
1795
|
+
with _background_lock:
|
|
1796
|
+
_background[response_id] = (call, response)
|
|
1797
|
+
_background.move_to_end(response_id)
|
|
1798
|
+
while len(_background) > _BACKGROUND_MAX_PENDING:
|
|
1799
|
+
evicted.append(_background.popitem(last=False)[1])
|
|
1800
|
+
for held, last_seen in evicted:
|
|
1801
|
+
_safe_finish(held, last_seen, status="abandoned")
|
|
1802
|
+
return True
|
|
1803
|
+
|
|
1804
|
+
|
|
1805
|
+
def _observe_background(response: Any) -> None:
|
|
1806
|
+
"""Record a held background call once its response reaches a terminal
|
|
1807
|
+
status; a non-terminal poll only updates the last status seen."""
|
|
1808
|
+
try:
|
|
1809
|
+
status = _get(response, "status")
|
|
1810
|
+
response_id = _get(response, "id")
|
|
1811
|
+
if not isinstance(response_id, str):
|
|
1812
|
+
return
|
|
1813
|
+
if status in _BACKGROUND_PENDING_STATUSES:
|
|
1814
|
+
with _background_lock:
|
|
1815
|
+
held = _background.get(response_id)
|
|
1816
|
+
if held is not None:
|
|
1817
|
+
_background[response_id] = (held[0], response)
|
|
1818
|
+
return
|
|
1819
|
+
if status not in _BACKGROUND_TERMINAL_STATUSES:
|
|
1820
|
+
return
|
|
1821
|
+
with _background_lock:
|
|
1822
|
+
held = _background.pop(response_id, None)
|
|
1823
|
+
if held is not None:
|
|
1824
|
+
_safe_finish(held[0], response)
|
|
1825
|
+
except Exception:
|
|
1826
|
+
pass
|
|
1827
|
+
|
|
1828
|
+
|
|
1829
|
+
def _observe_background_event(event: Any) -> None:
|
|
1830
|
+
"""Observe a streamed Responses event (``retrieve(..., stream=True)``)."""
|
|
1831
|
+
try:
|
|
1832
|
+
if str(_get(event, "type") or "").startswith("response."):
|
|
1833
|
+
response = _get(event, "response")
|
|
1834
|
+
if response is not None:
|
|
1835
|
+
_observe_background(response)
|
|
1836
|
+
except Exception:
|
|
1837
|
+
pass
|
|
1838
|
+
|
|
1839
|
+
|
|
1840
|
+
class _ObservedStream:
|
|
1841
|
+
"""Pass a resumed background stream through unchanged, observing its
|
|
1842
|
+
response events so the terminal one finishes the held call."""
|
|
1843
|
+
|
|
1844
|
+
def __init__(self, stream: Any) -> None:
|
|
1845
|
+
self._stream = stream
|
|
1846
|
+
|
|
1847
|
+
def __getattr__(self, name: str) -> Any:
|
|
1848
|
+
return getattr(self._stream, name)
|
|
1849
|
+
|
|
1850
|
+
def __iter__(self):
|
|
1851
|
+
for event in self._stream:
|
|
1852
|
+
_observe_background_event(event)
|
|
1853
|
+
yield event
|
|
1854
|
+
|
|
1855
|
+
def __next__(self):
|
|
1856
|
+
event = next(self._stream)
|
|
1857
|
+
_observe_background_event(event)
|
|
1858
|
+
return event
|
|
1859
|
+
|
|
1860
|
+
def __enter__(self):
|
|
1861
|
+
entered = self._stream.__enter__()
|
|
1862
|
+
if entered is not self._stream:
|
|
1863
|
+
self._stream = entered
|
|
1864
|
+
return self
|
|
1865
|
+
|
|
1866
|
+
def __exit__(self, *exc: Any) -> Any:
|
|
1867
|
+
return self._stream.__exit__(*exc)
|
|
1868
|
+
|
|
1869
|
+
async def __aiter__(self):
|
|
1870
|
+
async for event in self._stream:
|
|
1871
|
+
_observe_background_event(event)
|
|
1872
|
+
yield event
|
|
1873
|
+
|
|
1874
|
+
async def __anext__(self):
|
|
1875
|
+
event = await self._stream.__anext__()
|
|
1876
|
+
_observe_background_event(event)
|
|
1877
|
+
return event
|
|
1878
|
+
|
|
1879
|
+
async def __aenter__(self):
|
|
1880
|
+
entered = await self._stream.__aenter__()
|
|
1881
|
+
if entered is not self._stream:
|
|
1882
|
+
self._stream = entered
|
|
1883
|
+
return self
|
|
1884
|
+
|
|
1885
|
+
async def __aexit__(self, *exc: Any) -> Any:
|
|
1886
|
+
return await self._stream.__aexit__(*exc)
|
|
1887
|
+
|
|
1888
|
+
|
|
1889
|
+
def _observed(result: Any, streamed: bool) -> Any:
|
|
1890
|
+
# Only a call that asked for a stream is wrapped, so a Response model
|
|
1891
|
+
# (which is itself iterable) is always returned unchanged.
|
|
1892
|
+
if streamed:
|
|
1893
|
+
try:
|
|
1894
|
+
if hasattr(result, "__iter__") or hasattr(result, "__aiter__"):
|
|
1895
|
+
return _ObservedStream(result)
|
|
1896
|
+
except Exception:
|
|
1897
|
+
pass
|
|
1898
|
+
return result
|
|
1899
|
+
_observe_background(result)
|
|
1900
|
+
return result
|
|
1901
|
+
|
|
1902
|
+
|
|
1903
|
+
def finish_background_calls(status: str = "abandoned") -> int:
|
|
1904
|
+
"""Record every held background call whose final result was never observed."""
|
|
1905
|
+
with _background_lock:
|
|
1906
|
+
held = list(_background.values())
|
|
1907
|
+
_background.clear()
|
|
1908
|
+
for call, last_seen in held:
|
|
1909
|
+
_safe_finish(call, last_seen, status=status)
|
|
1910
|
+
return len(held)
|
|
1911
|
+
|
|
1912
|
+
|
|
1913
|
+
def _patch_background_observer(owner: Any, method_name: str) -> bool:
|
|
1914
|
+
original = getattr(owner, method_name, None)
|
|
1915
|
+
if not callable(original):
|
|
1916
|
+
return False
|
|
1917
|
+
if getattr(original, "__metergraph__", False):
|
|
1918
|
+
return True
|
|
1919
|
+
|
|
1920
|
+
@functools.wraps(original)
|
|
1921
|
+
def wrapped(*args, **kwargs):
|
|
1922
|
+
result = original(*args, **kwargs)
|
|
1923
|
+
streamed = kwargs.get("stream") is True
|
|
1924
|
+
if inspect.isawaitable(result):
|
|
1925
|
+
|
|
1926
|
+
async def await_result():
|
|
1927
|
+
return _observed(await result, streamed)
|
|
1928
|
+
|
|
1929
|
+
return await_result()
|
|
1930
|
+
return _observed(result, streamed)
|
|
1931
|
+
|
|
1932
|
+
wrapped.__metergraph__ = True # type: ignore[attr-defined]
|
|
1933
|
+
try:
|
|
1934
|
+
setattr(owner, method_name, wrapped)
|
|
1935
|
+
except Exception:
|
|
1936
|
+
return False
|
|
1937
|
+
return True
|
|
1938
|
+
|
|
1939
|
+
|
|
1940
|
+
def _apply_background_observers(client: Any) -> int:
|
|
1941
|
+
patched = 0
|
|
1942
|
+
for path in ("responses", "beta.responses"):
|
|
1943
|
+
try:
|
|
1944
|
+
owner = _resolve(client, path)
|
|
1945
|
+
except Exception:
|
|
1946
|
+
continue
|
|
1947
|
+
if owner is None:
|
|
1948
|
+
continue
|
|
1949
|
+
for method in ("retrieve", "cancel"):
|
|
1950
|
+
patched += int(_patch_background_observer(owner, method))
|
|
1951
|
+
return patched
|
|
1952
|
+
|
|
1953
|
+
|
|
1759
1954
|
def _finish_or_stream(
|
|
1760
1955
|
result: Any, call: CallState, endpoint: str, request: Mapping[str, Any]
|
|
1761
1956
|
):
|
|
@@ -1770,6 +1965,17 @@ def _finish_or_stream(
|
|
|
1770
1965
|
or (hasattr(result, "__enter__") and hasattr(result, "__exit__"))
|
|
1771
1966
|
):
|
|
1772
1967
|
return SyncStream(result, call)
|
|
1968
|
+
try:
|
|
1969
|
+
held = (
|
|
1970
|
+
endpoint in {"responses", "responses.parse"}
|
|
1971
|
+
and _get(result, "status") in _BACKGROUND_PENDING_STATUSES
|
|
1972
|
+
and (request.get("background") is True or _get(result, "background") is True)
|
|
1973
|
+
and _hold_background(call, result)
|
|
1974
|
+
)
|
|
1975
|
+
except Exception:
|
|
1976
|
+
held = False
|
|
1977
|
+
if held:
|
|
1978
|
+
return result
|
|
1773
1979
|
_safe_finish(call, result)
|
|
1774
1980
|
return result
|
|
1775
1981
|
|
|
@@ -1944,6 +2150,8 @@ def wrap(
|
|
|
1944
2150
|
patched_count = len(patched)
|
|
1945
2151
|
if not vercel:
|
|
1946
2152
|
patched_count += _apply_batch_extras(client, resolved_provider)
|
|
2153
|
+
if resolved_provider == "openai":
|
|
2154
|
+
patched_count += _apply_background_observers(client)
|
|
1947
2155
|
if vercel:
|
|
1948
2156
|
client_label = f"Vercel AI Gateway via {resolved_provider}"
|
|
1949
2157
|
elif gateway_name is not None:
|
|
@@ -687,6 +687,176 @@ _PRECEDENCE = (
|
|
|
687
687
|
)
|
|
688
688
|
|
|
689
689
|
|
|
690
|
+
# LiteLLM's OpenTelemetry callback writes this on every call span it produces.
|
|
691
|
+
_LITELLM_CALL_ID = "litellm.call_id"
|
|
692
|
+
# LiteLLM's tracer, which names its spans after the caller's generation_name.
|
|
693
|
+
LITELLM_SCOPE = "litellm"
|
|
694
|
+
# Span names LiteLLM uses when the caller did not name the call.
|
|
695
|
+
_LITELLM_DEFAULT_SPAN_NAMES = frozenset({"litellm_request", "raw_gen_ai_request"})
|
|
696
|
+
|
|
697
|
+
|
|
698
|
+
def _is_litellm(attributes: Mapping[str, Any]) -> bool:
|
|
699
|
+
return _LITELLM_CALL_ID in attributes
|
|
700
|
+
|
|
701
|
+
|
|
702
|
+
def litellm_route(span_name: Any, attributes: Mapping[str, Any]) -> str | None:
|
|
703
|
+
"""The caller's ``generation_name``, which LiteLLM writes as the span name.
|
|
704
|
+
|
|
705
|
+
None for a LiteLLM default name: ``litellm_request``, ``raw_gen_ai_request``
|
|
706
|
+
or the semantic-convention ``"<operation> <model>"``.
|
|
707
|
+
"""
|
|
708
|
+
if not _is_litellm(attributes) or not isinstance(span_name, str):
|
|
709
|
+
return None
|
|
710
|
+
name = span_name.strip()
|
|
711
|
+
if not name or name in _LITELLM_DEFAULT_SPAN_NAMES:
|
|
712
|
+
return None
|
|
713
|
+
operations = {"chat", _string(attributes.get("gen_ai.operation.name")) or "chat"}
|
|
714
|
+
if any(name == op or name.startswith(op + " ") for op in operations):
|
|
715
|
+
return None
|
|
716
|
+
return name
|
|
717
|
+
|
|
718
|
+
|
|
719
|
+
def _indexed(attributes: Mapping[str, Any], prefix: str) -> dict[int, dict[str, Any]]:
|
|
720
|
+
"""Group ``<prefix>.<i>.<field>`` attributes by index."""
|
|
721
|
+
grouped: dict[int, dict[str, Any]] = {}
|
|
722
|
+
lead = prefix + "."
|
|
723
|
+
for key, value in attributes.items():
|
|
724
|
+
if not key.startswith(lead):
|
|
725
|
+
continue
|
|
726
|
+
index, separator, rest = key[len(lead) :].partition(".")
|
|
727
|
+
if separator and index.isdigit() and rest:
|
|
728
|
+
grouped.setdefault(int(index), {})[rest] = value
|
|
729
|
+
return grouped
|
|
730
|
+
|
|
731
|
+
|
|
732
|
+
def _litellm_tools(attributes: Mapping[str, Any]) -> tuple[list[dict[str, Any]], bool]:
|
|
733
|
+
"""Request tools from ``llm.request.functions.<i>.*``, in OpenAI chat shape."""
|
|
734
|
+
tools: list[dict[str, Any]] = []
|
|
735
|
+
degraded = False
|
|
736
|
+
for _, fields in sorted(_indexed(attributes, "llm.request.functions").items()):
|
|
737
|
+
name = _string(fields.get("name"))
|
|
738
|
+
if name is None:
|
|
739
|
+
continue
|
|
740
|
+
function: dict[str, Any] = {"name": name}
|
|
741
|
+
description = fields.get("description")
|
|
742
|
+
if isinstance(description, str):
|
|
743
|
+
function["description"] = description
|
|
744
|
+
parameters = fields.get("parameters")
|
|
745
|
+
if isinstance(parameters, str):
|
|
746
|
+
decoded, ok = _load_json(parameters)
|
|
747
|
+
function["parameters"] = decoded if ok else parameters
|
|
748
|
+
degraded = degraded or not ok
|
|
749
|
+
tools.append({"type": "function", "function": function})
|
|
750
|
+
return tools, degraded
|
|
751
|
+
|
|
752
|
+
|
|
753
|
+
def _output_message_tool_calls(attributes: Mapping[str, Any]) -> list[dict[str, Any]]:
|
|
754
|
+
"""Output tool calls from ``tool_call`` parts of ``gen_ai.output.messages``."""
|
|
755
|
+
messages, ok = _load_json(attributes.get("gen_ai.output.messages"))
|
|
756
|
+
if not ok or not isinstance(messages, list):
|
|
757
|
+
return []
|
|
758
|
+
calls: list[dict[str, Any]] = []
|
|
759
|
+
for message in messages:
|
|
760
|
+
if not isinstance(message, Mapping) or not isinstance(message.get("parts"), list):
|
|
761
|
+
continue
|
|
762
|
+
for part in message["parts"]:
|
|
763
|
+
if not isinstance(part, Mapping) or part.get("type") != "tool_call":
|
|
764
|
+
continue
|
|
765
|
+
name = _string(part.get("name"))
|
|
766
|
+
if name is None or not name.strip():
|
|
767
|
+
continue
|
|
768
|
+
arguments = part.get("arguments")
|
|
769
|
+
calls.append(
|
|
770
|
+
{
|
|
771
|
+
"id": str(part.get("id") or part.get("call_id") or f"call-{len(calls)}"),
|
|
772
|
+
"type": "function",
|
|
773
|
+
"function": {
|
|
774
|
+
"name": name.strip(),
|
|
775
|
+
"arguments": arguments
|
|
776
|
+
if isinstance(arguments, str)
|
|
777
|
+
else json.dumps(arguments if arguments is not None else {}),
|
|
778
|
+
},
|
|
779
|
+
}
|
|
780
|
+
)
|
|
781
|
+
return calls
|
|
782
|
+
|
|
783
|
+
|
|
784
|
+
def _litellm_tool_calls(
|
|
785
|
+
attributes: Mapping[str, Any], response_id: str | None
|
|
786
|
+
) -> list[dict[str, Any]]:
|
|
787
|
+
"""Output tool calls from ``gen_ai.completion.<i>.function_call`` or ``.tool_calls``.
|
|
788
|
+
|
|
789
|
+
The legacy attributes carry no call id, so one is derived from the response
|
|
790
|
+
id and completion index exactly as the MeterGraph OTLP ingest does.
|
|
791
|
+
"""
|
|
792
|
+
prefix = response_id or "completion"
|
|
793
|
+
calls: list[dict[str, Any]] = []
|
|
794
|
+
|
|
795
|
+
def add(call_id: Any, name: Any, arguments: Any) -> None:
|
|
796
|
+
name = _string(name)
|
|
797
|
+
if name is None or not name.strip():
|
|
798
|
+
return
|
|
799
|
+
calls.append(
|
|
800
|
+
{
|
|
801
|
+
"id": str(call_id),
|
|
802
|
+
"type": "function",
|
|
803
|
+
"function": {
|
|
804
|
+
"name": name.strip(),
|
|
805
|
+
"arguments": arguments if isinstance(arguments, str) else "",
|
|
806
|
+
},
|
|
807
|
+
}
|
|
808
|
+
)
|
|
809
|
+
|
|
810
|
+
for index, fields in sorted(_indexed(attributes, "gen_ai.completion").items()):
|
|
811
|
+
add(
|
|
812
|
+
f"{prefix}-{index}",
|
|
813
|
+
fields.get("function_call.name"),
|
|
814
|
+
fields.get("function_call.arguments"),
|
|
815
|
+
)
|
|
816
|
+
for position, call in sorted(_indexed(fields, "tool_calls").items()):
|
|
817
|
+
add(
|
|
818
|
+
_string(call.get("id")) or f"{prefix}-{index}-{position}",
|
|
819
|
+
call.get("name"),
|
|
820
|
+
call.get("arguments"),
|
|
821
|
+
)
|
|
822
|
+
return calls
|
|
823
|
+
|
|
824
|
+
|
|
825
|
+
def _apply_litellm(
|
|
826
|
+
attributes: Mapping[str, Any],
|
|
827
|
+
request: dict[str, Any],
|
|
828
|
+
response: dict[str, Any],
|
|
829
|
+
) -> bool:
|
|
830
|
+
"""Fill the request id, request tools and output tool calls from LiteLLM's
|
|
831
|
+
non-standard attributes, only where the standard ones are absent.
|
|
832
|
+
|
|
833
|
+
Returns whether any JSON was malformed.
|
|
834
|
+
"""
|
|
835
|
+
response_id = _string(attributes.get("gen_ai.response.id"))
|
|
836
|
+
if response_id is not None and not any(
|
|
837
|
+
response.get(key) for key in ("_request_id", "response_id", "responseId", "id")
|
|
838
|
+
):
|
|
839
|
+
response["id"] = response_id
|
|
840
|
+
|
|
841
|
+
degraded = False
|
|
842
|
+
if "tools" not in request and "gen_ai.tool.definitions" not in attributes:
|
|
843
|
+
tools, degraded = _litellm_tools(attributes)
|
|
844
|
+
if tools:
|
|
845
|
+
request["tools"] = tools
|
|
846
|
+
|
|
847
|
+
# The standard part carries the real call id; the legacy attributes do not.
|
|
848
|
+
tool_calls = _output_message_tool_calls(attributes) or _litellm_tool_calls(
|
|
849
|
+
attributes, response_id
|
|
850
|
+
)
|
|
851
|
+
if tool_calls:
|
|
852
|
+
choices = response.get("choices") or [{}]
|
|
853
|
+
response["choices"] = [
|
|
854
|
+
{**choices[0], "message": {"role": "assistant", "tool_calls": tool_calls}},
|
|
855
|
+
*choices[1:],
|
|
856
|
+
]
|
|
857
|
+
return degraded
|
|
858
|
+
|
|
859
|
+
|
|
690
860
|
def _first_value(contributions: list[_Fields], name: str) -> Any:
|
|
691
861
|
for contribution in contributions:
|
|
692
862
|
value = getattr(contribution, name)
|
|
@@ -749,6 +919,12 @@ def map_span_attributes(
|
|
|
749
919
|
if output_structure is not None and response_text is None:
|
|
750
920
|
response["output"] = output_structure
|
|
751
921
|
|
|
922
|
+
litellm_degraded = (
|
|
923
|
+
_apply_litellm(attributes, request, response)
|
|
924
|
+
if _is_litellm(attributes)
|
|
925
|
+
else False
|
|
926
|
+
)
|
|
927
|
+
|
|
752
928
|
priced = next((c for c in contributions if c.cost is not None), None)
|
|
753
929
|
|
|
754
930
|
dropped: set[str] = set()
|
|
@@ -769,12 +945,17 @@ def map_span_attributes(
|
|
|
769
945
|
completion_start_time=_first_value(contributions, "completion_start_time"),
|
|
770
946
|
error_message=_first_value(contributions, "error_message"),
|
|
771
947
|
dialects=tuple(eligible),
|
|
772
|
-
parse_degraded=
|
|
773
|
-
|
|
774
|
-
),
|
|
948
|
+
parse_degraded=litellm_degraded
|
|
949
|
+
or any(contribution.parse_degraded for contribution in contributions),
|
|
775
950
|
usage_absent=usage_absent,
|
|
776
951
|
dropped_usage_keys=tuple(sorted(dropped)),
|
|
777
952
|
)
|
|
778
953
|
|
|
779
954
|
|
|
780
|
-
__all__ = [
|
|
955
|
+
__all__ = [
|
|
956
|
+
"LITELLM_SCOPE",
|
|
957
|
+
"MappedCall",
|
|
958
|
+
"SkipReason",
|
|
959
|
+
"litellm_route",
|
|
960
|
+
"map_span_attributes",
|
|
961
|
+
]
|
|
@@ -18,7 +18,12 @@ from opentelemetry.trace import StatusCode
|
|
|
18
18
|
from ._capture import _get_runtime
|
|
19
19
|
from ._context import CaptureContext
|
|
20
20
|
from ._failure_log import FailureLogger
|
|
21
|
-
from ._genai_attrs import
|
|
21
|
+
from ._genai_attrs import (
|
|
22
|
+
LITELLM_SCOPE,
|
|
23
|
+
SkipReason,
|
|
24
|
+
litellm_route,
|
|
25
|
+
map_span_attributes,
|
|
26
|
+
)
|
|
22
27
|
|
|
23
28
|
_SKIP_SCOPE = "scope"
|
|
24
29
|
|
|
@@ -166,6 +171,8 @@ class MetergraphGenAIExporter(SpanExporter):
|
|
|
166
171
|
),
|
|
167
172
|
None,
|
|
168
173
|
)
|
|
174
|
+
if named_route is None and scope_name == LITELLM_SCOPE:
|
|
175
|
+
named_route = litellm_route(span.name, attributes)
|
|
169
176
|
call = runtime.call_state(
|
|
170
177
|
provider,
|
|
171
178
|
mapped.operation,
|
|
@@ -1,7 +1,44 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: metergraph
|
|
3
|
+
Version: 0.6.11
|
|
4
|
+
Summary: Zero-dependency Python SDK for function-level LLM cost attribution across major LLM providers and gateways, including OpenAI, Anthropic, Gemini, and Vercel AI Gateway.
|
|
5
|
+
Author: Metergraph
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://www.metergraph.dev/
|
|
8
|
+
Project-URL: Documentation, https://github.com/metergraph/metergraphsdk/tree/main/python#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/metergraph/metergraphsdk
|
|
10
|
+
Project-URL: Issues, https://github.com/metergraph/metergraphsdk/issues
|
|
11
|
+
Project-URL: Release notes, https://github.com/metergraph/metergraphsdk/releases
|
|
12
|
+
Keywords: llm,llm-cost,llm-observability,cost-attribution,ai-agents,openai,anthropic,gemini,vercel-ai-sdk,vercel-ai-gateway,opentelemetry,self-hosted
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
15
|
+
Classifier: Typing :: Typed
|
|
16
|
+
Requires-Python: >=3.10
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
Provides-Extra: otel
|
|
19
|
+
Requires-Dist: opentelemetry-sdk>=1.30; extra == "otel"
|
|
20
|
+
Provides-Extra: dev
|
|
21
|
+
Requires-Dist: build>=1; extra == "dev"
|
|
22
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
23
|
+
Requires-Dist: openai<3,>=2.50.0; extra == "dev"
|
|
24
|
+
Requires-Dist: anthropic<1,>=0.40; extra == "dev"
|
|
25
|
+
Requires-Dist: google-genai>=1; extra == "dev"
|
|
26
|
+
Requires-Dist: opentelemetry-sdk>=1.30; extra == "dev"
|
|
27
|
+
|
|
1
28
|
# metergraph (Python)
|
|
2
29
|
|
|
3
|
-
|
|
4
|
-
|
|
30
|
+
See where your agentic AI application's LLM spend comes from. Attribute usage
|
|
31
|
+
to functions, agents, and workflows without changing provider call sites, then
|
|
32
|
+
send it to Metergraph Cloud or your self-hosted Metergraph server.
|
|
33
|
+
|
|
34
|
+
[Metergraph](https://www.metergraph.dev/) helps teams understand and optimize
|
|
35
|
+
agentic AI applications. This open-source, zero-runtime-dependency package
|
|
36
|
+
provides function-level LLM cost attribution for OpenAI, Anthropic, Gemini, and
|
|
37
|
+
Python Vercel AI Gateway clients. Paid Metergraph builds on that attribution
|
|
38
|
+
with experimentation and optimization across models, prompts, tools,
|
|
39
|
+
retrieval, context, batching, and caching. This package captures and
|
|
40
|
+
attributes usage; it does not run experiments or optimize your application.
|
|
41
|
+
|
|
5
42
|
Initialize Metergraph once, then wrap each provider client. `init()` reads the
|
|
6
43
|
token and other omitted options from the environment.
|
|
7
44
|
|
|
@@ -78,7 +115,7 @@ OpenRouter is captured the same way: point an OpenAI client at
|
|
|
78
115
|
`reported_cost_usd` to Chat Completions rows without changing the requested model
|
|
79
116
|
or the capture provider. A trusted custom domain uses
|
|
80
117
|
`metergraph.wrap(client, gateway="openrouter")`. The runnable
|
|
81
|
-
[Python OpenRouter example](../examples/
|
|
118
|
+
[Python OpenRouter example](../examples/integrations/providers/openrouter/python/) covers requested-vs-
|
|
82
119
|
served model, reported-vs-catalog cost, streaming usage, and the BYOK limitation.
|
|
83
120
|
|
|
84
121
|
## OpenTelemetry GenAI export
|
|
@@ -100,17 +137,40 @@ from metergraph.opentelemetry import MetergraphGenAIExporter
|
|
|
100
137
|
|
|
101
138
|
litellm.callbacks.append(OpenTelemetry(OpenTelemetryConfig(
|
|
102
139
|
exporter=MetergraphGenAIExporter(),
|
|
103
|
-
capture_message_content="SPAN_ONLY",
|
|
104
140
|
)))
|
|
141
|
+
|
|
142
|
+
response = litellm.completion(
|
|
143
|
+
model="openai/gpt-5-mini",
|
|
144
|
+
messages=messages,
|
|
145
|
+
metadata={"generation_name": "ticket-triage"},
|
|
146
|
+
)
|
|
105
147
|
```
|
|
106
148
|
|
|
149
|
+
- LiteLLM logs message content on its spans by default. Releases before 1.85
|
|
150
|
+
have no `capture_message_content` option, so leave it out.
|
|
151
|
+
- Do not set `litellm.turn_off_message_logging`. It removes messages, tool
|
|
152
|
+
definitions and outputs from the spans, so MeterGraph can count the calls but
|
|
153
|
+
cannot analyse them.
|
|
154
|
+
- Name each call with `metadata={"generation_name": "<workload name>"}`.
|
|
155
|
+
LiteLLM uses it as the span name and MeterGraph records it as the call's
|
|
156
|
+
route. Without it every call is stored under the route `chat`. A
|
|
157
|
+
`metergraph.route` or `gen_ai.prompt.name` span attribute still takes
|
|
158
|
+
precedence.
|
|
159
|
+
- To group the calls of a multi-step agent run into one trace, make them inside
|
|
160
|
+
one application span and set `USE_OTEL_LITELLM_REQUEST_SPAN=true`. Without
|
|
161
|
+
that variable LiteLLM writes each call onto the application span itself, and
|
|
162
|
+
only one of the calls is recorded.
|
|
163
|
+
- Pass a new `metadata` dict to each call. Reusing one dict across calls makes
|
|
164
|
+
LiteLLM 1.103 drop spans.
|
|
165
|
+
|
|
107
166
|
The exporter preserves OpenTelemetry trace identity, model/provider metadata,
|
|
108
167
|
token usage, latency, system instructions, ordered messages, and text output.
|
|
109
|
-
|
|
168
|
+
From LiteLLM spans it also records the provider response id as the request id,
|
|
169
|
+
the request's tool definitions, and the tool calls in the response. Text parts
|
|
110
170
|
are retained and replayable in the current POC pipeline. Calls containing other
|
|
111
171
|
part types retain their model, usage, timing, and status metadata, but those
|
|
112
172
|
parts are not replayable yet. See the runnable
|
|
113
|
-
[`
|
|
173
|
+
[`LiteLLM OpenTelemetry example`](../examples/integrations/telemetry/litellm/python/).
|
|
114
174
|
|
|
115
175
|
The exporter reads the OpenTelemetry `gen_ai.*` conventions, OpenInference
|
|
116
176
|
(Arize Phoenix), Langfuse and LangSmith spans. Dialects that label span kind
|
|
@@ -187,6 +247,20 @@ message batches are captured per inference while iterating a wrapped
|
|
|
187
247
|
rows carry real per-result usage and the batch pricing flag; job-management
|
|
188
248
|
polls themselves are not miscounted as model calls.
|
|
189
249
|
|
|
250
|
+
OpenAI Responses created with `background=True` are recorded once, when a
|
|
251
|
+
wrapped `client.responses.retrieve()` or `cancel()` first returns a terminal
|
|
252
|
+
status (`completed`, `failed`, `cancelled` or `incomplete`), with that
|
|
253
|
+
response's usage and output. Polls that still report `queued` or
|
|
254
|
+
`in_progress` add no rows, and latency runs from `create` to the observed
|
|
255
|
+
terminal response. A background response whose terminal status the process
|
|
256
|
+
never observes is recorded at `shutdown()` with status `abandoned` and
|
|
257
|
+
unknown usage, never as a completed call with zero tokens. A streamed
|
|
258
|
+
`retrieve(..., stream=True)` or `responses.stream(response_id=...)` resume is
|
|
259
|
+
observed through its terminal response event. Only retrieves made through the same wrapped client in the same process
|
|
260
|
+
are observed: a client derived with `with_options()` or `copy()`,
|
|
261
|
+
`with_raw_response`/`with_streaming_response` retrieves, and polling from a
|
|
262
|
+
different process leave the call to be recorded as `abandoned`.
|
|
263
|
+
|
|
190
264
|
## Batch-first execution (opt-in)
|
|
191
265
|
|
|
192
266
|
`metergraph.batch_first()` is a separate, explicitly opt-in code path from `wrap()`/capture: submit one request through a provider's Batch API, wait up to a caller-chosen deadline, and fall back to exactly one direct call if the batch hasn't finished in time. It is synchronous/blocking, matching this SDK's own background-work model — a daemon thread, not asyncio.
|
|
@@ -223,7 +297,7 @@ codebase you want instrumented:
|
|
|
223
297
|
|
|
224
298
|
```text
|
|
225
299
|
Instrument this codebase's LLM API costs with the `metergraph` PyPI package
|
|
226
|
-
(https://github.com/
|
|
300
|
+
(https://github.com/metergraph/metergraphsdk): pip install metergraph,
|
|
227
301
|
then wrap every OpenAI()/AsyncOpenAI(), Anthropic()/AsyncAnthropic(), and
|
|
228
302
|
genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
|
|
229
303
|
OpenAI or Anthropic clients pointed at https://ai-gateway.vercel.sh are Vercel
|
metergraph-0.6.9/pyproject.toml
DELETED
|
@@ -1,34 +0,0 @@
|
|
|
1
|
-
[project]
|
|
2
|
-
name = "metergraph"
|
|
3
|
-
version = "0.6.9"
|
|
4
|
-
description = "Fire-and-forget LLM spend capture for Metergraph"
|
|
5
|
-
readme = "README.md"
|
|
6
|
-
requires-python = ">=3.10"
|
|
7
|
-
license = "Apache-2.0"
|
|
8
|
-
authors = [{ name = "Pioneer Square Labs" }]
|
|
9
|
-
keywords = ["llm", "observability", "openai", "anthropic", "gemini", "vercel-ai-gateway", "cost-tracking"]
|
|
10
|
-
classifiers = [
|
|
11
|
-
"Intended Audience :: Developers",
|
|
12
|
-
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
13
|
-
"Typing :: Typed",
|
|
14
|
-
]
|
|
15
|
-
dependencies = []
|
|
16
|
-
|
|
17
|
-
[project.urls]
|
|
18
|
-
Homepage = "https://www.metergraph.dev/"
|
|
19
|
-
Repository = "https://github.com/PioneerSquareLabs/metergraphsdk"
|
|
20
|
-
Issues = "https://github.com/PioneerSquareLabs/metergraphsdk/issues"
|
|
21
|
-
|
|
22
|
-
[project.optional-dependencies]
|
|
23
|
-
otel = ["opentelemetry-sdk>=1.30"]
|
|
24
|
-
dev = ["build>=1", "pytest>=8", "openai>=2.50.0,<3", "anthropic>=0.40,<1", "google-genai>=1", "opentelemetry-sdk>=1.30"]
|
|
25
|
-
|
|
26
|
-
[build-system]
|
|
27
|
-
requires = ["setuptools>=68"]
|
|
28
|
-
build-backend = "setuptools.build_meta"
|
|
29
|
-
|
|
30
|
-
[tool.setuptools.packages.find]
|
|
31
|
-
where = ["src"]
|
|
32
|
-
|
|
33
|
-
[tool.pytest.ini_options]
|
|
34
|
-
testpaths = ["tests"]
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|