Skip to content

Commit 1319ddf

Browse files
langfuse-botlangfuse-bot
langfuse-bot
and
langfuse-bot
authored
feat(api): update API spec from langfuse/langfuse f5e96a9 (#1408)
Co-authored-by: langfuse-bot <[email protected]>
1 parent 6e52a65 commit 1319ddf

21 files changed

+1180
-3
lines changed

‎langfuse/api/__init__.py‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,14 @@
136136
OptionalObservationBody,
137137
OrganizationProject,
138138
OrganizationProjectsResponse,
139+
OtelAttribute,
140+
OtelAttributeValue,
141+
OtelResource,
142+
OtelResourceSpan,
143+
OtelScope,
144+
OtelScopeSpan,
145+
OtelSpan,
146+
OtelTraceResponse,
139147
PaginatedAnnotationQueueItems,
140148
PaginatedAnnotationQueues,
141149
PaginatedDatasetItems,
@@ -153,6 +161,7 @@
153161
Prompt,
154162
PromptMeta,
155163
PromptMetaListResponse,
164+
PromptType,
156165
Prompt_Chat,
157166
Prompt_Text,
158167
ResourceMeta,
@@ -221,6 +230,7 @@
221230
metrics,
222231
models,
223232
observations,
233+
opentelemetry,
224234
organizations,
225235
projects,
226236
prompt_version,
@@ -370,6 +380,14 @@
370380
"OptionalObservationBody",
371381
"OrganizationProject",
372382
"OrganizationProjectsResponse",
383+
"OtelAttribute",
384+
"OtelAttributeValue",
385+
"OtelResource",
386+
"OtelResourceSpan",
387+
"OtelScope",
388+
"OtelScopeSpan",
389+
"OtelSpan",
390+
"OtelTraceResponse",
373391
"PaginatedAnnotationQueueItems",
374392
"PaginatedAnnotationQueues",
375393
"PaginatedDatasetItems",
@@ -387,6 +405,7 @@
387405
"Prompt",
388406
"PromptMeta",
389407
"PromptMetaListResponse",
408+
"PromptType",
390409
"Prompt_Chat",
391410
"Prompt_Text",
392411
"ResourceMeta",
@@ -455,6 +474,7 @@
455474
"metrics",
456475
"models",
457476
"observations",
477+
"opentelemetry",
458478
"organizations",
459479
"projects",
460480
"prompt_version",

‎langfuse/api/client.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@
3030
from .resources.metrics.client import AsyncMetricsClient, MetricsClient
3131
from .resources.models.client import AsyncModelsClient, ModelsClient
3232
from .resources.observations.client import AsyncObservationsClient, ObservationsClient
33+
from .resources.opentelemetry.client import (
34+
AsyncOpentelemetryClient,
35+
OpentelemetryClient,
36+
)
3337
from .resources.organizations.client import (
3438
AsyncOrganizationsClient,
3539
OrganizationsClient,
@@ -136,6 +140,7 @@ def __init__(
136140
self.metrics = MetricsClient(client_wrapper=self._client_wrapper)
137141
self.models = ModelsClient(client_wrapper=self._client_wrapper)
138142
self.observations = ObservationsClient(client_wrapper=self._client_wrapper)
143+
self.opentelemetry = OpentelemetryClient(client_wrapper=self._client_wrapper)
139144
self.organizations = OrganizationsClient(client_wrapper=self._client_wrapper)
140145
self.projects = ProjectsClient(client_wrapper=self._client_wrapper)
141146
self.prompt_version = PromptVersionClient(client_wrapper=self._client_wrapper)
@@ -240,6 +245,9 @@ def __init__(
240245
self.metrics = AsyncMetricsClient(client_wrapper=self._client_wrapper)
241246
self.models = AsyncModelsClient(client_wrapper=self._client_wrapper)
242247
self.observations = AsyncObservationsClient(client_wrapper=self._client_wrapper)
248+
self.opentelemetry = AsyncOpentelemetryClient(
249+
client_wrapper=self._client_wrapper
250+
)
243251
self.organizations = AsyncOrganizationsClient(
244252
client_wrapper=self._client_wrapper
245253
)

‎langfuse/api/reference.md‎

Lines changed: 179 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2442,7 +2442,7 @@ client.health.health()
24422442

24432443
**Legacy endpoint for batch ingestion for Langfuse Observability.**
24442444

2445-
-> Please use the OpenTelemetry endpoint (`/api/public/otel`). Learn more: https://langfuse.com/integrations/native/opentelemetry
2445+
-> Please use the OpenTelemetry endpoint (`/api/public/otel/v1/traces`). Learn more: https://langfuse.com/integrations/native/opentelemetry
24462446

24472447
Within each batch, there can be multiple events.
24482448
Each event has a type, an id, a timestamp, metadata and a body.
@@ -3604,6 +3604,184 @@ client.observations.get_many()
36043604
<dl>
36053605
<dd>
36063606

3607+
**filter:** `typing.Optional[str]`
3608+
3609+
JSON string containing an array of filter conditions. When provided, this takes precedence over legacy filter parameters (userId, name, sessionId, tags, version, release, environment, fromTimestamp, toTimestamp).
3610+
Each filter condition has the following structure:
3611+
```json
3612+
[
3613+
{
3614+
"type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
3615+
"column": string, // Required. Column to filter on
3616+
"operator": string, // Required. Operator based on type:
3617+
// - datetime: ">", "<", ">=", "<="
3618+
// - string: "=", "contains", "does not contain", "starts with", "ends with"
3619+
// - stringOptions: "any of", "none of"
3620+
// - categoryOptions: "any of", "none of"
3621+
// - arrayOptions: "any of", "none of", "all of"
3622+
// - number: "=", ">", "<", ">=", "<="
3623+
// - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
3624+
// - numberObject: "=", ">", "<", ">=", "<="
3625+
// - boolean: "=", "<>"
3626+
// - null: "is null", "is not null"
3627+
"value": any, // Required (except for null type). Value to compare against. Type depends on filter type
3628+
"key": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
3629+
}
3630+
]
3631+
```
3632+
3633+
</dd>
3634+
</dl>
3635+
3636+
<dl>
3637+
<dd>
3638+
3639+
**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
3640+
3641+
</dd>
3642+
</dl>
3643+
</dd>
3644+
</dl>
3645+
3646+
3647+
</dd>
3648+
</dl>
3649+
</details>
3650+
3651+
## Opentelemetry
3652+
<details><summary><code>client.opentelemetry.<a href="src/langfuse/resources/opentelemetry/client.py">export_traces</a>(...)</code></summary>
3653+
<dl>
3654+
<dd>
3655+
3656+
#### 📝 Description
3657+
3658+
<dl>
3659+
<dd>
3660+
3661+
<dl>
3662+
<dd>
3663+
3664+
**OpenTelemetry Traces Ingestion Endpoint**
3665+
3666+
This endpoint implements the OTLP/HTTP specification for trace ingestion, providing native OpenTelemetry integration for Langfuse Observability.
3667+
3668+
**Supported Formats:**
3669+
- Binary Protobuf: `Content-Type: application/x-protobuf`
3670+
- JSON Protobuf: `Content-Type: application/json`
3671+
- Supports gzip compression via `Content-Encoding: gzip` header
3672+
3673+
**Specification Compliance:**
3674+
- Conforms to [OTLP/HTTP Trace Export](https://opentelemetry.io/docs/specs/otlp/#otlphttp)
3675+
- Implements `ExportTraceServiceRequest` message format
3676+
3677+
**Documentation:**
3678+
- Integration guide: https://langfuse.com/integrations/native/opentelemetry
3679+
- Data model: https://langfuse.com/docs/observability/data-model
3680+
</dd>
3681+
</dl>
3682+
</dd>
3683+
</dl>
3684+
3685+
#### 🔌 Usage
3686+
3687+
<dl>
3688+
<dd>
3689+
3690+
<dl>
3691+
<dd>
3692+
3693+
```python
3694+
from langfuse import (
3695+
OtelAttribute,
3696+
OtelAttributeValue,
3697+
OtelResource,
3698+
OtelResourceSpan,
3699+
OtelScope,
3700+
OtelScopeSpan,
3701+
OtelSpan,
3702+
)
3703+
from langfuse.client import FernLangfuse
3704+
3705+
client = FernLangfuse(
3706+
x_langfuse_sdk_name="YOUR_X_LANGFUSE_SDK_NAME",
3707+
x_langfuse_sdk_version="YOUR_X_LANGFUSE_SDK_VERSION",
3708+
x_langfuse_public_key="YOUR_X_LANGFUSE_PUBLIC_KEY",
3709+
username="YOUR_USERNAME",
3710+
password="YOUR_PASSWORD",
3711+
base_url="https://yourhost.com/path/to/api",
3712+
)
3713+
client.opentelemetry.export_traces(
3714+
resource_spans=[
3715+
OtelResourceSpan(
3716+
resource=OtelResource(
3717+
attributes=[
3718+
OtelAttribute(
3719+
key="service.name",
3720+
value=OtelAttributeValue(
3721+
string_value="my-service",
3722+
),
3723+
),
3724+
OtelAttribute(
3725+
key="service.version",
3726+
value=OtelAttributeValue(
3727+
string_value="1.0.0",
3728+
),
3729+
),
3730+
],
3731+
),
3732+
scope_spans=[
3733+
OtelScopeSpan(
3734+
scope=OtelScope(
3735+
name="langfuse-sdk",
3736+
version="2.60.3",
3737+
),
3738+
spans=[
3739+
OtelSpan(
3740+
trace_id="0123456789abcdef0123456789abcdef",
3741+
span_id="0123456789abcdef",
3742+
name="my-operation",
3743+
kind=1,
3744+
start_time_unix_nano="1747872000000000000",
3745+
end_time_unix_nano="1747872001000000000",
3746+
attributes=[
3747+
OtelAttribute(
3748+
key="langfuse.observation.type",
3749+
value=OtelAttributeValue(
3750+
string_value="generation",
3751+
),
3752+
)
3753+
],
3754+
status={},
3755+
)
3756+
],
3757+
)
3758+
],
3759+
)
3760+
],
3761+
)
3762+
3763+
```
3764+
</dd>
3765+
</dl>
3766+
</dd>
3767+
</dl>
3768+
3769+
#### ⚙️ Parameters
3770+
3771+
<dl>
3772+
<dd>
3773+
3774+
<dl>
3775+
<dd>
3776+
3777+
**resource_spans:** `typing.Sequence[OtelResourceSpan]` — Array of resource spans containing trace data as defined in the OTLP specification
3778+
3779+
</dd>
3780+
</dl>
3781+
3782+
<dl>
3783+
<dd>
3784+
36073785
**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
36083786

36093787
</dd>

‎langfuse/api/resources/__init__.py‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
metrics,
1616
models,
1717
observations,
18+
opentelemetry,
1819
organizations,
1920
projects,
2021
prompt_version,
@@ -175,6 +176,16 @@
175176
from .metrics import MetricsResponse
176177
from .models import CreateModelRequest, PaginatedModels
177178
from .observations import Observations, ObservationsViews
179+
from .opentelemetry import (
180+
OtelAttribute,
181+
OtelAttributeValue,
182+
OtelResource,
183+
OtelResourceSpan,
184+
OtelScope,
185+
OtelScopeSpan,
186+
OtelSpan,
187+
OtelTraceResponse,
188+
)
178189
from .organizations import (
179190
DeleteMembershipRequest,
180191
MembershipDeletionResponse,
@@ -210,6 +221,7 @@
210221
Prompt,
211222
PromptMeta,
212223
PromptMetaListResponse,
224+
PromptType,
213225
Prompt_Chat,
214226
Prompt_Text,
215227
TextPrompt,
@@ -389,6 +401,14 @@
389401
"OptionalObservationBody",
390402
"OrganizationProject",
391403
"OrganizationProjectsResponse",
404+
"OtelAttribute",
405+
"OtelAttributeValue",
406+
"OtelResource",
407+
"OtelResourceSpan",
408+
"OtelScope",
409+
"OtelScopeSpan",
410+
"OtelSpan",
411+
"OtelTraceResponse",
392412
"PaginatedAnnotationQueueItems",
393413
"PaginatedAnnotationQueues",
394414
"PaginatedDatasetItems",
@@ -406,6 +426,7 @@
406426
"Prompt",
407427
"PromptMeta",
408428
"PromptMetaListResponse",
429+
"PromptType",
409430
"Prompt_Chat",
410431
"Prompt_Text",
411432
"ResourceMeta",
@@ -474,6 +495,7 @@
474495
"metrics",
475496
"models",
476497
"observations",
498+
"opentelemetry",
477499
"organizations",
478500
"projects",
479501
"prompt_version",

‎langfuse/api/resources/ingestion/client.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ def batch(
3333
"""
3434
**Legacy endpoint for batch ingestion for Langfuse Observability.**
3535
36-
-> Please use the OpenTelemetry endpoint (`/api/public/otel`). Learn more: https://langfuse.com/integrations/native/opentelemetry
36+
-> Please use the OpenTelemetry endpoint (`/api/public/otel/v1/traces`). Learn more: https://langfuse.com/integrations/native/opentelemetry
3737
3838
Within each batch, there can be multiple events.
3939
Each event has a type, an id, a timestamp, metadata and a body.
@@ -151,7 +151,7 @@ async def batch(
151151
"""
152152
**Legacy endpoint for batch ingestion for Langfuse Observability.**
153153
154-
-> Please use the OpenTelemetry endpoint (`/api/public/otel`). Learn more: https://langfuse.com/integrations/native/opentelemetry
154+
-> Please use the OpenTelemetry endpoint (`/api/public/otel/v1/traces`). Learn more: https://langfuse.com/integrations/native/opentelemetry
155155
156156
Within each batch, there can be multiple events.
157157
Each event has a type, an id, a timestamp, metadata and a body.

0 commit comments

Comments
 (0)