feat(core): move to OTEL backbone

Author: hassiebp

langfuse/otel/__init__.py

@@ -0,0 +1,10 @@
+import logging
+
+logger = logging.getLogger("langfuse")
+
+# handle httpx logging
+httpx_logger = logging.getLogger("httpx")
+httpx_logger.setLevel(logging.WARNING)  # Set the desired log level
+
+console_handler = logging.StreamHandler()
+httpx_logger.addHandler(console_handler)

langfuse/otel/_logger.py

@@ -0,0 +1,52 @@
+import json
+
+from opentelemetry import trace as otel_trace_api
+from opentelemetry.sdk import util
+from opentelemetry.sdk.trace import ReadableSpan
+
+
+def span_formatter(span: ReadableSpan):
+    parent_id = None
+    if span.parent is not None:
+        parent_id = f"0x{otel_trace_api.format_span_id(span.parent.span_id)}"
+
+    start_time = None
+    if span._start_time:
+        start_time = util.ns_to_iso_str(span._start_time)
+
+    end_time = None
+    if span._end_time:
+        end_time = util.ns_to_iso_str(span._end_time)
+
+    status = {
+        "status_code": str(span._status.status_code.name),
+    }
+    if span._status.description:
+        status["description"] = span._status.description
+
+    return (
+        json.dumps(
+            {
+                "name": span._name,
+                "context": (
+                    span._format_context(span._context) if span._context else None
+                ),
+                "kind": str(span.kind),
+                "parent_id": parent_id,
+                "start_time": start_time,
+                "end_time": end_time,
+                "status": status,
+                "attributes": span._format_attributes(span._attributes),
+                "events": span._format_events(span._events),
+                "links": span._format_links(span._links),
+                "resource": json.loads(span.resource.to_json()),
+                "instrumentationScope": json.loads(
+                    span._instrumentation_scope.to_json()
+                    if span._instrumentation_scope
+                    else "{}"
+                ),
+            },
+            indent=2,
+        )
+        + "\n"
+    )

langfuse/otel/_utils.py

@@ -0,0 +1,140 @@
+import json
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from langfuse.model import PromptClient
+
+from ..serializer import EventSerializer
+from ..types import MapValue, SpanLevel
+
+
+class LangfuseSpanAttributes:
+    # Langfuse-Trace attributes
+    TRACE_NAME = "langfuse.trace.name"
+    TRACE_ID = "langfuse.trace.id"
+    TRACE_USER_ID = "user.id"
+    TRACE_SESSION_ID = "session.id"
+    TRACE_TAGS = "langfuse.trace.tags"
+    TRACE_PUBLIC = "langfuse.trace.public"
+    TRACE_METADATA = "langfuse.trace.metadata"
+    TRACE_INPUT = "langfuse.trace.input"
+    TRACE_OUTPUT = "langfuse.trace.output"
+
+    # Langfuse-observation attributes
+    OBSERVATION_NAME = "langfuse.observation.name"
+    OBSERVATION_TYPE = "langfuse.observation.type"
+    OBSERVATION_METADATA = "langfuse.observation.metadata"
+    OBSERVATION_LEVEL = "langfuse.observation.level"
+    OBSERVATION_STATUS_MESSAGE = "langfuse.observation.status_message"
+    OBSERVATION_INPUT = "langfuse.observation.input"
+    OBSERVATION_OUTPUT = "langfuse.observation.output"
+
+    # Langfuse-observation of type Generation attributes
+    OBSERVATION_COMPLETION_START_TIME = "langfuse.observation.completion_start_time"
+    OBSERVATION_MODEL = "gen_ai.response.model"
+    OBSERVATION_MODEL_PARAMETERS = "langfuse.observation.model_parameters"
+    OBSERVATION_USAGE_DETAILS = "gen_ai.usage"
+    OBSERVATION_COST_DETAILS = "langfuse.observation.cost_details"
+    OBSERVATION_PROMPT_NAME = "langfuse.observation.prompt.name"
+    OBSERVATION_PROMPT_VERSION = "langfuse.observation.prompt.version"
+
+    # General
+    ENVIRONMENT = "langfuse.environment"
+    RELEASE = "langfuse.release"
+    VERSION = "langfuse.version"
+
+
+def create_trace_attributes(
+    *,
+    name: Optional[str] = None,
+    user_id: Optional[str] = None,
+    session_id: Optional[str] = None,
+    version: Optional[str] = None,
+    release: Optional[str] = None,
+    input: Optional[Any] = None,
+    output: Optional[Any] = None,
+    metadata: Optional[Any] = None,
+    tags: Optional[List[str]] = None,
+    public: Optional[bool] = None,
+):
+    attributes = {
+        LangfuseSpanAttributes.TRACE_NAME: name,
+        LangfuseSpanAttributes.TRACE_USER_ID: user_id,
+        LangfuseSpanAttributes.TRACE_SESSION_ID: session_id,
+        LangfuseSpanAttributes.VERSION: version,
+        LangfuseSpanAttributes.RELEASE: release,
+        LangfuseSpanAttributes.TRACE_INPUT: _serialize(input),
+        LangfuseSpanAttributes.TRACE_OUTPUT: _serialize(output),
+        LangfuseSpanAttributes.TRACE_METADATA: _serialize(metadata),
+        LangfuseSpanAttributes.TRACE_TAGS: tags,
+        LangfuseSpanAttributes.TRACE_PUBLIC: public,
+    }
+
+    return {k: v for k, v in attributes.items() if v is not None}
+
+
+def create_span_attributes(
+    *,
+    metadata: Optional[Any] = None,
+    input: Optional[Any] = None,
+    output: Optional[Any] = None,
+    level: Optional[SpanLevel] = None,
+    status_message: Optional[str] = None,
+    version: Optional[str] = None,
+):
+    attributes = {
+        LangfuseSpanAttributes.OBSERVATION_TYPE: "span",
+        LangfuseSpanAttributes.OBSERVATION_LEVEL: level,
+        LangfuseSpanAttributes.OBSERVATION_STATUS_MESSAGE: status_message,
+        LangfuseSpanAttributes.VERSION: version,
+        LangfuseSpanAttributes.OBSERVATION_INPUT: _serialize(input),
+        LangfuseSpanAttributes.OBSERVATION_OUTPUT: _serialize(output),
+        LangfuseSpanAttributes.OBSERVATION_METADATA: _serialize(metadata),
+    }
+
+    return {k: v for k, v in attributes.items() if v is not None}
+
+
+def create_generation_attributes(
+    *,
+    name: Optional[str] = None,
+    completion_start_time: Optional[datetime] = None,
+    metadata: Optional[Any] = None,
+    level: Optional[SpanLevel] = None,
+    status_message: Optional[str] = None,
+    version: Optional[str] = None,
+    model: Optional[str] = None,
+    model_parameters: Optional[Dict[str, MapValue]] = None,
+    input: Optional[Any] = None,
+    output: Optional[Any] = None,
+    usage_details: Optional[Dict[str, int]] = None,
+    cost_details: Optional[Dict[str, float]] = None,
+    prompt: Optional[PromptClient] = None,
+):
+    attributes = {
+        LangfuseSpanAttributes.OBSERVATION_TYPE: "generation",
+        LangfuseSpanAttributes.OBSERVATION_NAME: name,
+        LangfuseSpanAttributes.OBSERVATION_LEVEL: level,
+        LangfuseSpanAttributes.OBSERVATION_STATUS_MESSAGE: status_message,
+        LangfuseSpanAttributes.VERSION: version,
+        LangfuseSpanAttributes.OBSERVATION_INPUT: _serialize(input),
+        LangfuseSpanAttributes.OBSERVATION_OUTPUT: _serialize(output),
+        LangfuseSpanAttributes.OBSERVATION_METADATA: _serialize(metadata),
+        LangfuseSpanAttributes.OBSERVATION_MODEL: model,
+        LangfuseSpanAttributes.OBSERVATION_PROMPT_NAME: prompt and prompt.name,
+        LangfuseSpanAttributes.OBSERVATION_PROMPT_VERSION: prompt and prompt.version,
+        LangfuseSpanAttributes.OBSERVATION_USAGE_DETAILS: _serialize(usage_details),
+        LangfuseSpanAttributes.OBSERVATION_COST_DETAILS: _serialize(cost_details),
+        LangfuseSpanAttributes.OBSERVATION_COMPLETION_START_TIME: _serialize(
+            completion_start_time
+        ),
+        LangfuseSpanAttributes.OBSERVATION_MODEL_PARAMETERS: _serialize(
+            model_parameters
+        ),
+    }
+
+    return {k: v for k, v in attributes.items() if v is not None}
+
+
+def _serialize(obj):
+    return json.dumps(obj, cls=EventSerializer) if obj is not None else None

langfuse/otel/attributes.py

@@ -0,0 +1 @@
+LANGFUSE_TRACER_NAME = "langfuse-sdk"

langfuse/otel/constants.py

@@ -0,0 +1,45 @@
+# Desired DX
+
+## Option 1: Langfuse classic
+
+```python
+from langfuse import langfuse
+
+langfuse = Langfuse()
+
+trace = langfuse.trace(id='trace-123', name='my_trace', tags=['tag1', 'tag2'], metadata={"key1": "val"})
+span = langfuse.span(id='span-123', name='my-span')
+generation = langfuse.generation(input='hello', output="what's up", usage_details={"input_tokens": 1, "output_tokens": 2})
+
+generation.end()
+span.end()
+trace.end()
+```
+
+## Option 2: OTEL native, i.e. use spans throughout
+
+```python
+from langfuse import langfuse
+
+langfuse = Langfuse()
+
+root_span = langfuse.span(trace={"id": "new-trace-id", name: "new-trace-name"}, id="root-span-id")
+regular_span = langfuse.span(id='span-123', name='my-span')
+generation = langfuse.span(as_type="generation", input='hello', output="what's up", usage_details={"input_tokens": 1, "output_tokens": 2})
+
+generation.end()
+span.end()
+trace.end()
+```
+
+## Late updates
+
+```python
+trace_1 = langfuse.trace()
+trace_2 = langfuse.trace()
+
+trace_1.span()
+trace_2.span()
+
+trace_1
+```

langfuse/otel/dx.md

@@ -0,0 +1,51 @@
+LANGFUSE_TRACING_ENVIRONMENT = "LANGFUSE_TRACING_ENVIRONMENT"
+"""
+.. envvar:: LANGFUSE_TRACING_ENVIRONMENT
+
+The tracing environment. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'.
+
+**Default value:** ``"default"``
+"""
+
+LANGFUSE_RELEASE = "LANGFUSE_RELEASE"
+"""
+.. envvar:: LANGFUSE_TRACING_ENVIRONMENT
+
+Release number/hash of the application to provide analytics grouped by release.
+"""
+
+
+LANGFUSE_PUBLIC_KEY = "LANGFUSE_PUBLIC_KEY"
+"""
+.. envvar:: LANGFUSE_PUBLIC_KEY
+
+Public API key of Langfuse project
+"""
+
+LANGFUSE_SECRET_KEY = "LANGFUSE_SECRET_KEY"
+"""
+.. envvar:: LANGFUSE_SECRET_KEY
+
+Secret API key of Langfuse project
+"""
+
+LANGFUSE_HOST = "LANGFUSE_HOST"
+"""
+.. envvar:: LANGFUSE_HOST
+
+Host of Langfuse API. Can be set via `LANGFUSE_HOST` environment variable. Defaults to `https://cloud.langfuse.com`.
+"""
+
+LANGFUSE_DEBUG = "LANGFUSE_DEBUG"
+"""
+.. envvar:: LANGFUSE_DEBUG
+
+Enables debug mode for more verbose logging.
+"""
+
+LANGFUSE_TRACING_ENABLED = "LANGFUSE_TRACING_ENABLED"
+"""
+.. envvar:: LANGFUSE_TRACING_ENABLED
+
+Enables or disables the Langfuse client. If disabled, all observability calls to the backend will be no-ops. Default is True. Set to `False` to disable tracing.
+"""