This section introduces the Langfuse observability log application for large model monitoring, available in the TLS application marketplace.

Overview

The Langfuse SDK is an observability and platform integration library embedded in LLM/Agent applications. It records execution processes and reports them to Langfuse, and also provides capabilities for prompt management, evaluation, and scoring. The Python and JavaScript/TypeScript SDKs are primarily maintained. For more details, refer to the Langfuse official documentation.

By integrating the Langfuse observability log application, TLS automatically creates a dedicated Langfuse Trace log topic, generates visual charts, and displays session, trace, token, and tool invocation data, enabling trace tracking and observability. It can be used in the following scenarios:

Observability	Description
Performance analysis	Model invocation latency distribution Tool execution time ranking Token consumption trend
Error tracking	View the complete invocation chain Locate the error segment Analyze the cause of the error
Cost optimization	Identify high-consumption conversations Optimize prompts to reduce tokens Select a more cost-effective model

Prerequisites

Category	Description
Region restriction	Deploy the server for the Langfuse SDK application and TLS in the same region to ensure network connectivity.
Authentication method	Obtain the user's Access Key ID, Secret Access Key, or APIKey according to the authentication method. AK/SK: AccessKey ID and AccessKey Secret for Volcano Engine accounts. Obtain them on the Volcano Engine console Key Management page. We recommend using IAM user keys. Ensure this user has the required permissions. For details, see IAM overview. Supports automatic creation of TLS resources (project/app/topic) and auto-generates log topic IDs. API Key: A key credential for requesting Volcano TLS. It is used only for reporting Log, Metric, and Trace data. Enforces strict permissions and does not support auto creation of TLS resources. It is suitable for multi-data center environments and strict permission management scenarios. Notice API Key is in closed beta. If needed, contact your account manager for access to the allowlist.

1. Integrate the Langfuse log application

Log in to TLS console.

Select the region where log service is located from the top navigation bar.

In the left navigation bar, select AgentLoop > AI observability.

On the AI observability page, click Integrate AI observability.

On the Integrate AI observability page, create an application.

Click the Langfuse icon and select the Langfuse application.

Configure the integration application parameters, then click Create application.

Parameters	Description
Region	The region where the log application data is stored.
Log project	Select the project where the log application data is stored. Notice After the log application is created successfully, a log topic with the LANGFUSE tag will be automatically created in the project to store trace data. The relevant information for this log topic is as follows: Log topic name: ApplicationName_trace Number of shards: 2 Log storage period: Standard storage for 90 days Index: A key-value index is automatically configured.
Application name	Enter the name of the Langfuse log application. Length must be between 3 and 64 characters. Only supports Chinese, lowercase letters, numbers, underscores (_), and hyphens (-). Can not start or end with a hyphen (-) or underscore (_). Cannot start with tls_, tos_, or certain reserved fields.
Description	Description information for the log application. Length limit is 0–128 characters.

After creating the application, proceed to the next step to obtain usage instructions and integrate the log application.

2. Integrate Langfuse application data

Obtain usage instructions for integrating Langfuse application data.

Go to the Integration configuration page.

Obtain when integrating the log application
Obtain after integrating the log application
When creating a Langfuse log application in AgentLoop, follow the interface prompts to obtain the corresponding usage guide.
Refer to 1. Integrate the Langfuse log application to integrate the Langfuse log application.
On the Integrate AI observability page, in Integration configuration, configure the following information to obtain the usage guide.
Log in to TLS console.
Select the region where log service is located from the top navigation bar.
In the left navigation bar, select AgentLoop > AI observability.
On the AI Monitoring page, access the usage guide page as follows.
Click the integration configuration icon in the Actions column of the target log application.
Click the target log application name, then click Integration Management.

On the Integration configuration page, select the authentication method, configure the following information, and obtain usage instructions.

AK/SK integration
API Key integration
For Integration Method, select AK SK Integration.
For Connection Method, select Public Network or Volcano Engine Internal Network based on actual requirements.
In Usage Guide, copy the Auto generation usage guide.
For Integration Method, select API Key Integration.
For Connection Method, select Public Network or Volcano Engine Internal Network based on actual requirements.
For API Key, select the created API Key.
In Usage Guide, copy the Auto generation usage guide.

Usage instruction example (AK/SK integration method):

Public network
Volcano Engine internal network

## Python Langfuse integration

This integration method retains the original Langfuse `get_client()` and `langfuse.openai.OpenAI` and reports trace instance generated by Langfuse to the current TLS instance via OTLP/HTTP.

### 1. Install dependencies

```bash
python -m pip install -U langfuse opentelemetry-exporter-otlp-proto-http
```

To run the Ark model calls in the examples, install the following packages:

```bash
python -m pip install -U openai
```

### 2. Add an initialization file

Put the given `tls_langfuse_bootstrap.py` into app code directory and make sure it can be imported to the module.

```python
"""Register a TLS OTLP exporter for clients returned by ``get_client()``."""

import os
from typing import Optional

from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
OTLPSpanExporter,
)

from langfuse import Langfuse

_bootstrap_client: Optional[Langfuse] = None

_REQUIRED_ENV_VARS = (
"LANGFUSE_PUBLIC_KEY",
"LANGFUSE_SECRET_KEY",
"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
"OTEL_EXPORTER_OTLP_TRACES_HEADERS",
)

def init_langfuse_tls() -> Langfuse:
"""Initialize the shared Langfuse resource manager with a TLS exporter.

Call this once, before the first call to ``get_client()`` or the first
instrumented model request. Later ``get_client()`` calls reuse the resource
manager and exporter registered here.
"""
global _bootstrap_client

if _bootstrap_client is not None:
return _bootstrap_client

missing = [name for name in _REQUIRED_ENV_VARS if not os.environ.get(name)]
if missing:
missing_names = ", ".join(missing)
message = f"Missing required environment variables: {missing_names}"
raise RuntimeError(message)

endpoint = os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"].rstrip("/")
if not endpoint.startswith("https://"):
message = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT must use HTTPS"
raise ValueError(message)

if not endpoint.endswith("/v1/traces"):
message = (
"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT must end with /v1/traces; "
"signal-specific OTEL endpoints are used without path rewriting"
)
raise ValueError(message)

# OTLPSpanExporter reads its endpoint, headers, and timeout from the
# standard OTEL_EXPORTER_OTLP_TRACES_* environment variables.
tls_exporter = OTLPSpanExporter()

# Creating this client registers a resource manager keyed by the Langfuse
# public key. Existing business code can continue to call get_client().
_bootstrap_client = Langfuse(span_exporter=tls_exporter)
return _bootstrap_client
```
### 3. Configure environment variables

```bash
# Langfuse SDK initialization identifier.
# Trace authentication is completed by the TLS AK/SK below.
export LANGFUSE_PUBLIC_KEY="Requires manual replace of the actual tls-ak"
export LANGFUSE_SECRET_KEY="Requires manual replace of the actual tls-sk"

# TLS OTLP/HTTP public network endpoint
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://The system autopopulates the current endpoint:4318/v1/traces"

# Replace <your-ak> and <your-sk> with your Volcano Engine access keys
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="x-tls-otel-tracetopic=<The system autopopulates the trace-topic-id>,x-tls-otel-ak=<Requires manual replace of the actual your-ak>,x-tls-otel-sk=<Requires manual replace of the actual your-sk>,x-tls-otel-region=<The system autopopulates the current region>"
```

Inject AK/SK via the deployment platform's Secrets or environment variables. Do not hardcode credentials in source code or Dockerfile.

### 4. Initialize Langfuse

Add the following code to the application startup entry point and ensure it runs before the first call to get_client() or traced model requests:

```python
from tls_langfuse_bootstrap import init_langfuse_tls

init_langfuse_tls()
```

Existing business code can remain unchanged.

```python
from langfuse import get_client

langfuse = get_client()
```

If the application is a short-lived process such as a script or task, flush the Trace before exit:

```python
langfuse.flush()
```

(AK/SK method only) Modify the authentication information in the usage instructions.

Enter the obtained Access Key ID and Secret Access Key into the AK and SK fields in the usage instructions, respectively.

Integrate Langfuse observability logs into the log application.

Log in to the server where Langfuse is deployed.

Run the commands obtained from the usage instructions to install the TLS plugin.

After the plugin installation is complete, restart the Langfuse service.

Return to the TLS console to view the observability chart data.

Monitoring chart details

The monitoring chart details for the TLS Langfuse application observability are as follows:

Type	Chart
Homepage	Request overview: Session count, conversation count, model request count, tool invocation count, request trends Cost overview: Total Tokens, Input Tokens, Output Tokens, Cache Read Tokens, Reasoning Tokens, Token consumption trend, model invocation trend Tool overview Number of successful invocations, number of failed invocations, tool invocation latency P90, tool invocation Top 10, tool invocation failure Top 10, tool invocation trend Model performance overview Model invocation distribution Top 10, model invocation latency P90, provider invocation distribution, provider invocation latency P90
Trace analysis	Homepage Total trace count, total token consumption, average tokens, P90 duration Trace call chain analysis Displays the Input, Output, Trace ID, Total Tokens, Input Tokens, Output Tokens, latency (s), start time, end time, and more for the specified call chain.
Session analysis	Homepage Session count, total token consumption, model request count, average session tokens Session analysis Displays the First Input, Last Output, Session ID, Total Tokens, total latency (ms), number of call chains, latency (s), model, start time, end time, and more for the specified session.
Token analysis	Homepage Total Tokens, Input Tokens, Output Tokens, Cache Read Tokens, Reasoning Tokens, Input Tokens (excluding Cache), Top 10 session token consumption, Top 10 model token consumption, token category proportion
Topic list	Displays the log types, projects, log topics, description information, and more generated by the current log application.

Manage my applications

After the log application is successfully connected, you can manage connected log applications as follows:

AgentLoop

Application marketplace

Log in to TLS console.

Select the region where log service is located from the top navigation bar.

In the left navigation bar, select AgentLoop > AI Monitoring.

On the AI Monitoring page, in the Actions column of the corresponding log application, the following management operations are supported:

Edit application information: Click the edit icon to modify the application name and description.

Obtain usage guide: Click the access configuration icon to open the access configuration popup, where you can obtain sample usage guide information.

Delete my application: Click the delete icon to delete this log application.

Application name_trace (log topic) log fields

Field	Type	Description
Attributes	json	Custom key-value pairs mounted on the Span, recording business-related information.
Duration	long	Span duration (End - Start), measuring the time consumed by the operation.
End	long	Span end time.
Events	text	Events occurring during the Span lifecycle.
Host	text	The host running the service.
Kind	text	The type of the Span.
Links	text	References to other Spans (used for cross-Trace associations, such as asynchronous task scenarios).
Name	text	The name of the Span, usually describing the operation.
OTLPName	text	The original name when reported via the OTLP protocol (OTLP = OpenTelemetry Line Protocol).
OTLPVersion	text	The version number of the OTLP protocol used.
ParentSpanID	text	The ID of the parent Span, indicating which operation triggered the current operation. This field is empty for the root node.
Resource	json	A set of attributes describing the service itself (more comprehensive than ServiceName), such as service name, version, runtime environment, and so on.
ServiceName	text	The name of the service that generated this Span.
SpanID	text	The unique ID of the current Span.
Start	long	Span start time.
StatusCode	text	The execution result of the Span.
StatusDescription	text	Supplementary description of the Span's execution result.
TracelD	text	The TraceID of the entire call chain. All Spans for the same request share the same TraceID.
TraceState	text	Custom trace context metadata.

Attributes

Field	Type	Description
langfuse.observation.cost_details	text	Cost details, typically including input token cost, output token cost, total cost, and so on.
langfuse.observation.input	text	Observed input content, such as prompt and similar items.
langfuse.observation.metadata.provider	text	The LLM service provider called.
langfuse.observation.model.name	text	The name of the model called.
langfuse.observation.output	text	Observed output content.
langfuse.observation.type	text	Type of the observed node.
langfuse.observation.usage_details	text	Token usage details, typically including input_tokens (number of input tokens), output_tokens (number of output tokens), and total_tokens (total number of tokens).
session.id	text	Session ID.
user.id	text	User ID.

Torch Log Service