Skip to content

feat(api): update API spec from langfuse/langfuse c3d6c8b #1407

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
langfuse-bot wants to merge 1 commit into from
Closed

feat(api): update API spec from langfuse/langfuse c3d6c8b #1407

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions langfuse/api/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,14 @@
OptionalObservationBody,
OrganizationProject,
OrganizationProjectsResponse,
OtelAttribute,
OtelAttributeValue,
OtelResource,
OtelResourceSpan,
OtelScope,
OtelScopeSpan,
OtelSpan,
OtelTraceResponse,
PaginatedAnnotationQueueItems,
PaginatedAnnotationQueues,
PaginatedDatasetItems,
Expand All @@ -153,6 +161,7 @@
Prompt,
PromptMeta,
PromptMetaListResponse,
PromptType,
Prompt_Chat,
Prompt_Text,
ResourceMeta,
Expand Down Expand Up @@ -221,6 +230,7 @@
metrics,
models,
observations,
opentelemetry,
organizations,
projects,
prompt_version,
Expand Down Expand Up @@ -370,6 +380,14 @@
"OptionalObservationBody",
"OrganizationProject",
"OrganizationProjectsResponse",
"OtelAttribute",
"OtelAttributeValue",
"OtelResource",
"OtelResourceSpan",
"OtelScope",
"OtelScopeSpan",
"OtelSpan",
"OtelTraceResponse",
"PaginatedAnnotationQueueItems",
"PaginatedAnnotationQueues",
"PaginatedDatasetItems",
Expand All @@ -387,6 +405,7 @@
"Prompt",
"PromptMeta",
"PromptMetaListResponse",
"PromptType",
"Prompt_Chat",
"Prompt_Text",
"ResourceMeta",
Expand Down Expand Up @@ -455,6 +474,7 @@
"metrics",
"models",
"observations",
"opentelemetry",
"organizations",
"projects",
"prompt_version",
Expand Down
8 changes: 8 additions & 0 deletions langfuse/api/client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,10 @@
from .resources.metrics.client import AsyncMetricsClient, MetricsClient
from .resources.models.client import AsyncModelsClient, ModelsClient
from .resources.observations.client import AsyncObservationsClient, ObservationsClient
from .resources.opentelemetry.client import (
AsyncOpentelemetryClient,
OpentelemetryClient,
)
from .resources.organizations.client import (
AsyncOrganizationsClient,
OrganizationsClient,
Expand Down Expand Up @@ -136,6 +140,7 @@ def __init__(
self.metrics = MetricsClient(client_wrapper=self._client_wrapper)
self.models = ModelsClient(client_wrapper=self._client_wrapper)
self.observations = ObservationsClient(client_wrapper=self._client_wrapper)
self.opentelemetry = OpentelemetryClient(client_wrapper=self._client_wrapper)
self.organizations = OrganizationsClient(client_wrapper=self._client_wrapper)
self.projects = ProjectsClient(client_wrapper=self._client_wrapper)
self.prompt_version = PromptVersionClient(client_wrapper=self._client_wrapper)
Expand Down Expand Up @@ -240,6 +245,9 @@ def __init__(
self.metrics = AsyncMetricsClient(client_wrapper=self._client_wrapper)
self.models = AsyncModelsClient(client_wrapper=self._client_wrapper)
self.observations = AsyncObservationsClient(client_wrapper=self._client_wrapper)
self.opentelemetry = AsyncOpentelemetryClient(
client_wrapper=self._client_wrapper
)
self.organizations = AsyncOrganizationsClient(
client_wrapper=self._client_wrapper
)
Expand Down
148 changes: 147 additions & 1 deletion langfuse/api/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2442,7 +2442,7 @@ client.health.health()

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

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

Within each batch, there can be multiple events.
Each event has a type, an id, a timestamp, metadata and a body.
Expand Down Expand Up @@ -3612,6 +3612,152 @@ client.observations.get_many()
</dl>


</dd>
</dl>
</details>

## Opentelemetry
Copy link
Contributor

@ellipsis-dev ellipsis-dev bot Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo: The header currently reads ## Opentelemetry. It should likely be corrected to ## OpenTelemetry to match the standard naming used later in the documentation.

Suggested change
## Opentelemetry
## OpenTelemetry

<details><summary><code>client.opentelemetry.<a href="src/langfuse/resources/opentelemetry/client.py">export_traces</a>(...)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

**OpenTelemetry Traces Ingestion Endpoint**

This endpoint implements the OTLP/HTTP specification for trace ingestion, providing native OpenTelemetry integration for Langfuse Observability.

**Supported Formats:**
- Binary Protobuf: `Content-Type: application/x-protobuf`
- JSON Protobuf: `Content-Type: application/json`
- Supports gzip compression via `Content-Encoding: gzip` header

**Specification Compliance:**
- Conforms to [OTLP/HTTP Trace Export](https://opentelemetry.io/docs/specs/otlp/#otlphttp)
- Implements `ExportTraceServiceRequest` message format

**Documentation:**
- Integration guide: https://langfuse.com/integrations/native/opentelemetry
- Data model: https://langfuse.com/docs/observability/data-model
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from langfuse import (
OtelAttribute,
OtelAttributeValue,
OtelResource,
OtelResourceSpan,
OtelScope,
OtelScopeSpan,
OtelSpan,
)
from langfuse.client import FernLangfuse

client = FernLangfuse(
x_langfuse_sdk_name="YOUR_X_LANGFUSE_SDK_NAME",
x_langfuse_sdk_version="YOUR_X_LANGFUSE_SDK_VERSION",
x_langfuse_public_key="YOUR_X_LANGFUSE_PUBLIC_KEY",
username="YOUR_USERNAME",
password="YOUR_PASSWORD",
base_url="https://yourhost.com/path/to/api",
)
client.opentelemetry.export_traces(
resource_spans=[
OtelResourceSpan(
resource=OtelResource(
attributes=[
OtelAttribute(
key="service.name",
value=OtelAttributeValue(
string_value="my-service",
),
),
OtelAttribute(
key="service.version",
value=OtelAttributeValue(
string_value="1.0.0",
),
),
],
),
scope_spans=[
OtelScopeSpan(
scope=OtelScope(
name="langfuse-sdk",
version="2.60.3",
),
spans=[
OtelSpan(
trace_id="0123456789abcdef0123456789abcdef",
span_id="0123456789abcdef",
name="my-operation",
kind=1,
start_time_unix_nano="1747872000000000000",
end_time_unix_nano="1747872001000000000",
attributes=[
OtelAttribute(
key="langfuse.observation.type",
value=OtelAttributeValue(
string_value="generation",
),
)
],
status={},
)
],
)
],
)
],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**resource_spans:** `typing.Sequence[OtelResourceSpan]` — Array of resource spans containing trace data as defined in the OTLP specification

</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.

</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>
Expand Down
22 changes: 22 additions & 0 deletions langfuse/api/resources/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
metrics,
models,
observations,
opentelemetry,
organizations,
projects,
prompt_version,
Expand Down Expand Up @@ -175,6 +176,16 @@
from .metrics import MetricsResponse
from .models import CreateModelRequest, PaginatedModels
from .observations import Observations, ObservationsViews
from .opentelemetry import (
OtelAttribute,
OtelAttributeValue,
OtelResource,
OtelResourceSpan,
OtelScope,
OtelScopeSpan,
OtelSpan,
OtelTraceResponse,
)
from .organizations import (
DeleteMembershipRequest,
MembershipDeletionResponse,
Expand Down Expand Up @@ -210,6 +221,7 @@
Prompt,
PromptMeta,
PromptMetaListResponse,
PromptType,
Prompt_Chat,
Prompt_Text,
TextPrompt,
Expand Down Expand Up @@ -389,6 +401,14 @@
"OptionalObservationBody",
"OrganizationProject",
"OrganizationProjectsResponse",
"OtelAttribute",
"OtelAttributeValue",
"OtelResource",
"OtelResourceSpan",
"OtelScope",
"OtelScopeSpan",
"OtelSpan",
"OtelTraceResponse",
"PaginatedAnnotationQueueItems",
"PaginatedAnnotationQueues",
"PaginatedDatasetItems",
Expand All @@ -406,6 +426,7 @@
"Prompt",
"PromptMeta",
"PromptMetaListResponse",
"PromptType",
"Prompt_Chat",
"Prompt_Text",
"ResourceMeta",
Expand Down Expand Up @@ -474,6 +495,7 @@
"metrics",
"models",
"observations",
"opentelemetry",
"organizations",
"projects",
"prompt_version",
Expand Down
4 changes: 2 additions & 2 deletions langfuse/api/resources/ingestion/client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ def batch(
"""
**Legacy endpoint for batch ingestion for Langfuse Observability.**

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

Within each batch, there can be multiple events.
Each event has a type, an id, a timestamp, metadata and a body.
Expand Down Expand Up @@ -151,7 +151,7 @@ async def batch(
"""
**Legacy endpoint for batch ingestion for Langfuse Observability.**

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

Within each batch, there can be multiple events.
Each event has a type, an id, a timestamp, metadata and a body.
Expand Down
23 changes: 23 additions & 0 deletions langfuse/api/resources/opentelemetry/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# This file was auto-generated by Fern from our API Definition.

from .types import (
OtelAttribute,
OtelAttributeValue,
OtelResource,
OtelResourceSpan,
OtelScope,
OtelScopeSpan,
OtelSpan,
OtelTraceResponse,
)

__all__ = [
"OtelAttribute",
"OtelAttributeValue",
"OtelResource",
"OtelResourceSpan",
"OtelScope",
"OtelScopeSpan",
"OtelSpan",
"OtelTraceResponse",
]
Loading