+
+
+
+ );
+}
+```
+
+
+
+
+This documentation is for the Python SDK v3. Documentation for the legacy Python SDK v2 can be found [here](https://python-sdk-v2.docs-snapshot.langfuse.com/docs/observability/sdk/python/decorators).
+
+
+This documentation is for the TypeScript SDK v4. Documentation for the legacy TypeScript SDK v3 can be found [here](https://js-sdk-v3.docs-snapshot.langfuse.com/docs/observability/sdk/typescript/guide/).
+
+
-## Python
+
-
+Legacy documentation
-- Based on OpenTelemetry, so you can use any OTEL-based instrumentation library for your LLM. -- Fully async requests, using Langfuse adds almost no latency -- Accurate latency tracking using synchronous timestamps -- IDs available for downstream use -- Great DX when nesting observations -- Cannot break your application, all errors are caught and logged -- Interoperable with Langfuse [integrations](/integrations) +
- 
-
+
+
+
+If you are self-hosting Langfuse, the Python SDK v3 requires [**Langfuse platform version >= 3.63.0**](https://github.com/langfuse/langfuse/releases/tag/v3.63.0) for traces to be correctly processed.
+
+
+
+
-## JS/TS
+If you are self-hosting Langfuse, the TypeScript SDK v4 requires **Langfuse platform version ≥ 3.95.0** for all features to work correctly.
+
+
+
-import JSSDKPackages from "@/components-mdx/js-sdk-packages.mdx";
+
+
+
+
+
+**Key benefits**
+
+- Based on OpenTelemetry, so you can use any OTEL-based instrumentation library for your LLM stack.
+- Fully async requests, meaning Langfuse adds almost no latency.
+- Accurate latency tracking via synchronous timestamps.
+- IDs available for downstream use.
+- Great DX when nesting observations.
+- Cannot break your application—SDK errors are caught and logged.
+- Interoperable with Langfuse [integrations](/integrations).
+
+## Quickstart
+
+Follow the path for your runtime to get the first trace into Langfuse.
+
+Requirements for self-hosted Langfuse
-Please see our [Python SDK documentation](/docs/observability/sdk/python/overview) on how to get started. +
+
+
+Key configuration options
+ +All key configuration options are listed in the [Python SDK reference](https://python.reference.langfuse.com/langfuse#Langfuse). + +| Constructor Argument | Environment Variable | Description | Default value | +| --------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | +| `public_key` | `LANGFUSE_PUBLIC_KEY` | Your Langfuse project's public API key. **Required.** | | +| `secret_key` | `LANGFUSE_SECRET_KEY` | Your Langfuse project's secret API key. **Required.** | | +| `base_url` | `LANGFUSE_BASE_URL` | API host for your Langfuse instance. | `"https://cloud.langfuse.com"` | +| `timeout` | `LANGFUSE_TIMEOUT` | Timeout in seconds for API requests. | `5` | +| `httpx_client` | - | Custom `httpx.Client` for non-tracing HTTP requests. | | +| `debug` | `LANGFUSE_DEBUG` | Enables verbose logging. | `False` | +| `tracing_enabled` | `LANGFUSE_TRACING_ENABLED` | Toggles Langfuse instrumentation; if `False`, tracing calls become no-ops. | `True` | +| `flush_at` | `LANGFUSE_FLUSH_AT` | Number of spans to batch before sending. | `512` | +| `flush_interval` | `LANGFUSE_FLUSH_INTERVAL` | Seconds between batch flushes. | `5` | +| `environment` | `LANGFUSE_TRACING_ENVIRONMENT` | Environment name (lowercase alphanumeric, hyphen/underscore). | `"default"` | +| `release` | `LANGFUSE_RELEASE` | Release identifier for grouping analytics. | | +| `media_upload_thread_count` | `LANGFUSE_MEDIA_UPLOAD_THREAD_COUNT` | Background threads for media uploads. | `1` | +| `sample_rate` | `LANGFUSE_SAMPLE_RATE` | [Sampling](/docs/observability/features/sampling) rate between `0.0` and `1.0`. | `1.0` | +| `mask` | - | [Mask](/docs/observability/sdk/advanced-features#mask-sensitive-data) sensitive data before export. | | +| | `LANGFUSE_MEDIA_UPLOAD_ENABLED` | Whether to upload media files to Langfuse storage (useful to disable when self-hosting). | `True` | + +
+
+
+
+Alternative: configure via constructor
+ +```python filename="Initialize client" +from langfuse import Langfuse + +langfuse = Langfuse( + public_key="pk-lf-...", + secret_key="sk-lf-...", + base_url="https://cloud.langfuse.com" +) +``` +
+
+
+
+Alternative: configure via constructor
+ +```ts filename="client.ts" +import { LangfuseClient } from "@langfuse/client"; + +const langfuse = new LangfuseClient({ + publicKey: "your-public-key", + secretKey: "your-secret-key", + baseUrl: "https://cloud.langfuse.com", +}); +``` + +Context Propagation --> Child_OTEL_Span + end + + subgraph Langfuse_Mapping ["Langfuse"] + direction LR + LF_Trace["Langfuse Trace"] + LF_Observation["Langfuse Observation
(typed as either Span, Generation or Event)"] + + LF_Trace -- Collects one or more --> LF_Observation + end + + OTEL_Trace -.->|shares ID with | LF_Trace + + Root_OTEL_Span -.->|Mapped to| LF_Observation + Child_OTEL_Span -.->|Mapped to| LF_Observation + + Root_OTEL_Span -.->|sets default input and output | LF_Trace + Root_OTEL_Span -.->|can hold trace attributes| LF_Trace + Child_OTEL_Span -.->|can hold trace attributes| LF_Trace + + classDef otel fill:#D6EAF8,stroke:#3498DB,stroke-width:2px,color:#000; + classDef langfuse fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px,color:#000; + class OTEL_Trace,Root_OTEL_Span,Child_OTEL_Span otel; + class LF_Trace,LF_Observation langfuse; +``` + +## Learn more -## Other Languages +
-
- }
- title="Vercel AI SDK"
- href="/integrations/frameworks/vercel-ai-sdk"
- arrow
- />
- 
-
- }
- title="Llamaindex"
- href="/integrations/frameworks/llamaindex"
- arrow
- />
- 
-
- }
- title="CrewAI"
- href="/integrations/frameworks/crewai"
- arrow
- />
- 
-
- }
- title="Ollama"
- href="/integrations/model-providers/ollama"
- arrow
- />
- 
-
- }
- title="LiteLLM"
- href="/integrations/gateways/litellm"
- arrow
- />
- 
-
- }
- title="AutoGen"
- href="/integrations/frameworks/autogen"
- arrow
- />
- 
-
- }
- title="Google ADK"
- href="/integrations/frameworks/google-adk"
- arrow
- />
- Context Propagation --> Child_OTEL_Span - end - - subgraph Langfuse_Mapping ["Langfuse"] - direction LR - LF_Trace["Langfuse Trace"] - LF_Observation["Langfuse Observation
(typed as either Span, Generation or Event)"] - - LF_Trace -- Collects one or more --> LF_Observation - end - - OTEL_Trace -.->|shares ID with | LF_Trace - - Root_OTEL_Span -.->|Mapped to| LF_Observation - Child_OTEL_Span -.->|Mapped to| LF_Observation - - Root_OTEL_Span -.->|sets default input and output | LF_Trace - Root_OTEL_Span -.->|can hold trace attributes| LF_Trace - Child_OTEL_Span -.->|can hold trace attributes| LF_Trace - - classDef otel fill:#D6EAF8,stroke:#3498DB,stroke-width:2px,color:#000; - classDef langfuse fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px,color:#000; - class OTEL_Trace,Root_OTEL_Span,Child_OTEL_Span otel; - class LF_Trace,LF_Observation langfuse; -``` - -- **OTel Trace**: An OTel-trace represents the entire lifecycle of a request or transaction as it moves through your application and its services. A trace is typically a sequence of operations, like an LLM generating a response followed by a parsing step. The root (first) span created in a sequence defines the OTel trace. OTel traces do not have a start and end time, they are defined by the root span. -- **OTel Span**: A span represents a single unit of work or operation within a trace. Spans have a start and end time, a name, and can have attributes (key-value pairs of metadata). Spans can be nested to create a hierarchy, showing parent-child relationships between operations. -- **Langfuse Trace**: A Langfuse trace collects observations and holds trace attributes such as `session_id`, `user_id` as well as overall input and outputs. It shares the same ID as the OTel trace and its attributes are set via specific OTel span attributes that are automatically propagated to the Langfuse trace. -- **Langfuse Observation**: In Langfuse terminology, an "observation" is a Langfuse-specific representation of an OTel span. It can be a generic span (Langfuse-span), a specialized "generation" (Langfuse-generation), a point-in-time event (Langfuse-event), or [other observation types](/docs/observability/features/observation-types). - - **Langfuse Span**: A Langfuse-span is a generic OTel span in Langfuse, designed for non-LLM operations. - - **Langfuse Generation**: A Langfuse-generation is a specialized type of OTel span in Langfuse, designed specifically for Large Language Model (LLM) calls. It includes additional fields like `model`, `model_parameters`, `usage_details` (tokens), and `cost_details`. - - **Langfuse Event**: A Langfuse-event tracks a point in time action. -- **Context Propagation**: OpenTelemetry automatically handles the propagation of the current trace and span context. This means when you call another function (whether it's also traced by Langfuse, an OTel-instrumented library, or a manually created span), the new span will automatically become a child of the currently active span, forming a correct trace hierarchy. -- **Attribute Propagation**: Certain trace attributes (`user_id`, `session_id`, `metadata`, `version`, `tags`) can be automatically propagated to all child observations using `propagate_attributes()`. This ensures consistent attribute coverage across all observations in a trace. See the [instrumentation docs](/docs/observability/sdk/python/instrumentation#propagating-trace-attributes) for details. - -The Langfuse SDK provides wrappers around OTel spans (`LangfuseSpan`, `LangfuseGeneration`) that offer convenient methods for interacting with Langfuse-specific features like scoring and media handling, while still being native OTel spans under the hood. You can also use these wrapper objects to add Langfuse trace attributes via `update_trace()` or use `propagate_attributes()` for automatic propagation to all child observationss. - diff --git a/pages/docs/observability/sdk/python/setup.mdx b/pages/docs/observability/sdk/python/setup.mdx deleted file mode 100644 index 5963002c4..000000000 --- a/pages/docs/observability/sdk/python/setup.mdx +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Setup of the Langfuse Python SDK -description: Setup the Langfuse Python SDK for tracing your application and ingesting data into Langfuse. -category: SDKs ---- - -# Setup - -To get started with the Langfuse Python SDK, you need to install the SDK and initialize the client. - -
-
-
-Key configuration options:
-
-| Constructor Argument | Environment Variable | Description | Default value |
-| --------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| `public_key` | `LANGFUSE_PUBLIC_KEY` | Your Langfuse project's public API key. **Required.** | |
-| `secret_key` | `LANGFUSE_SECRET_KEY` | Your Langfuse project's secret API key. **Required.** | |
-| `base_url` | `LANGFUSE_BASE_URL` | The API host for your Langfuse instance. | `"https://cloud.langfuse.com"` |
-| `timeout` | `LANGFUSE_TIMEOUT` | Timeout in seconds for API requests. | `5` |
-| `httpx_client` | - | Custom `httpx.Client` for making non-tracing HTTP requests. | |
-| `debug` | `LANGFUSE_DEBUG` | Enables debug mode for more verbose logging. Set to `True` or `"True"`. | `False` |
-| `tracing_enabled` | `LANGFUSE_TRACING_ENABLED` | Enables or disables the Langfuse client. If `False`, all observability calls become no-ops. | `True` |
-| `flush_at` | `LANGFUSE_FLUSH_AT` | Number of spans to batch before sending to the API. | `512` |
-| `flush_interval` | `LANGFUSE_FLUSH_INTERVAL` | Time in seconds between batch flushes. | `5` |
-| `environment` | `LANGFUSE_TRACING_ENVIRONMENT` | Environment name for tracing (e.g., "development", "staging", "production"). Must be lowercase alphanumeric with hyphens/underscores. | `"default"` |
-| `release` | `LANGFUSE_RELEASE` | [Release](/docs/tracing-features/releases-and-versioning) version/hash of your application. Used for grouping analytics. | |
-| `media_upload_thread_count` | `LANGFUSE_MEDIA_UPLOAD_THREAD_COUNT` | Number of background threads for handling media uploads. | `1` |
-| `sample_rate` | `LANGFUSE_SAMPLE_RATE` | [Sampling](/docs/tracing-features/sampling) rate for traces (float between 0.0 and 1.0). `1.0` means 100% of traces are sampled. | `1.0` |
-| `mask` | - | A function `(data: Any) -> Any` to [mask](/docs/tracing-features/masking) sensitive data in traces before sending to the API. | |
-| | `LANGFUSE_MEDIA_UPLOAD_ENABLED` | Whether to upload media files to Langfuse S3. In self-hosted environments this might be useful to disable. | `True` |
-
--Verify connection with `langfuse.auth_check()` -
- -You can also verify your connection to the Langfuse server using `langfuse.auth_check()`. We do not recommend using this in production as this adds latency to your application. - -```python -from langfuse import get_client - -langfuse = get_client() - -# Verify connection, do not use in production as this is a synchronous call -if langfuse.auth_check(): - print("Langfuse client is authenticated and ready!") -else: - print("Authentication failed. Please check your credentials and host.") -``` - -
-
-
-
- );
-}
-```
-
-
-
-
-
-
-
-
-```
-
-
-
-
-