Bỏ qua để đến nội dung

Langfuse Observability

Nội dung này hiện chưa có sẵn bằng ngôn ngữ của bạn.

Add Langfuse trace viewing to an existing py#agent, both during local development and after deployment. This experimental component generator supports Python Strands, HTTP, AgentCore zip deployment (infra: agentcore), CDK, and IAM authentication. It preserves the agent’s model, tools, and configured session storage.

Other languages, frameworks, protocols, MCP servers, containers, Terraform, and infra: none are rejected. Langfuse export selects AgentCore platform V1 and fails CDK validation for V2: credentials and exporter connections must not be captured in an unqualified startup snapshot. The generator does not deploy Langfuse or create a secret.

Existing agents continue using their generated tracing setup unless you run this generator. Langfuse starts on the next local dev run; deployed agents switch after you rebuild and redeploy. As an experimental generator, its output may change without an upgrade migration; users must review and reconcile those changes themselves.

Signal or featureEffect with Langfuse enabled
Agent/model/tool application spansExported to Langfuse. These spans are no longer delivered to aws/spans or the runtime’s application spans stream.
Runtime service metricsInvocations, Latency, UserErrors, and SystemErrors remain available in CloudWatch.
Agent stdout/stderrUvicorn logs and application output still go to the runtime’s CloudWatch log group. Prompts or tool results printed by your app can therefore remain in AWS logs too.
ADOT structured telemetry logsDisabled with ADOT. Ordinary application logs continue independently. Restoring ADOT restores its structured telemetry logs.
Separately delivered AgentCore service spansNot redirected by this application exporter. Check the separate delivery configuration for Memory, Gateway, Identity, and built-in tools; this integration does not configure or guarantee their delivery.
AgentCore EvaluationsCloudWatch-backed online/batch evaluation and CloudWatchAgentSpanCollector lose new application spans for this agent. The on-demand Evaluate API can accept caller-supplied spans, but this generator supplies no replacement collector.
Application tests, dashboards, and evaluation jobsGenerated application tests do not require CloudWatch traces. Any dashboards, alarms, or evaluation jobs that read application spans from CloudWatch lose those new spans. Check the trace source used by each integration before enabling Langfuse.

See AWS’s supported evaluation telemetry and observability configuration for service delivery and evaluation requirements.

Prompts, completions, model usage, and tool inputs/outputs from local and deployed invocations are sent to the configured Langfuse endpoint. With Langfuse Cloud, this data leaves your laptop or AWS environment for a third-party service. With self-hosted Langfuse, it goes to the host you select. Check that endpoint, region, retention, and access controls against your data-handling requirements before enabling export. This generator does not redact trace content.

CloudWatch/X-Ray usage charges associated with the switched-off application traces decrease; runtime metrics and log charges remain. Langfuse has its own plan or hosting costs, and Secrets Manager and outbound transfer may add charges. There is no dual-export cost in this version.

The exporter batches spans and attempts a flush before each invocation’s final response frame, with an 8-second flush timeout inside a 10-second guard. This can add up to 10 seconds of latency before the final response frame. Export failures or an interrupted process can still lose telemetry; traces are not a durable audit log.

Commit your existing workspace changes before running this generator. Review and commit the Langfuse changes, including dependency installation, separately so you can revert the integration later.

Chạy generator này@aws/nx-plugin:observability#langfuse

pnpm nx g @aws/nx-plugin:observability#langfuse
Xây dựng lệnh của bạn5

Bắt buộc

Use the project name recorded in project.json. If it contains several agents, also pass the agent component’s name with --agent.

Tùy chọn của generator5 tùy chọn
projectBắt buộcstring

Project containing the Python agent

hoststring

HTTPS base URL of an existing Langfuse installation, including any self-hosted path prefix. Required on first use; re-runs retain the previous value. There is no default destination.

secretArnstring

Complete ARN of an existing Secrets Manager secret containing LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY. Required when first enabling Langfuse; never pass key values.

agentstring

Agent component name; required when the project contains multiple Python agents

preferInstallDependenciesbooleanMặc định: true

Install dependencies after generation

We recommend self-hosting Langfuse on AWS when choosing where to keep your trace data. Use an existing, secured HTTPS installation; this generator does not provision one. Langfuse Cloud is also supported when you explicitly select its endpoint.

Create a Secrets Manager secret in the agent’s AWS account and region. Its JSON must contain the string fields LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY with your Langfuse project’s keys. Use the Secrets Manager console or an approved secret-management process; do not put keys in generator flags, source files, shell history, or runtime environment variables.

Use the AWS managed Secrets Manager encryption key for this first version. A secret encrypted with a customer-managed KMS key needs an additional, explicitly scoped decrypt grant that this generator does not create.

Pass the secret’s complete ARN, including its six-character suffix, and the HTTPS base URL of an existing Langfuse deployment, such as one you already host on AWS. The endpoint must be reachable from both your development machine and the deployed agent. There is no default destination; --host is required on first use. This experimental generator accepts ARNs in the aws, aws-us-gov, and aws-cn partitions; ISO partitions are not supported.

Terminal window
pnpm nx g @aws/nx-plugin:observability#langfuse \
--project=my_agent \
--secretArn="$LANGFUSE_SECRET_ARN" \
--host=https://langfuse.example.com

Here LANGFUSE_SECRET_ARN contains only the ARN, not a key. CDK grants secretsmanager:GetSecretValue on exactly that ARN. The application loads both keys once at process startup and constructs Basic authentication in memory. Arrange a runtime restart when rotating keys; an unchanged CDK deployment does not refresh running processes.

The CDK helper writes the host and secret ARN to AppConfig at agentcore.langfuse.<AgentClass>, preserving entries for other agents. Deployed startup reads this entry through get_agentcore_runtime_config(), using the agent’s existing AppConfig read grant. The generated runtime sets DISABLE_ADOT_OBSERVABILITY=true so AgentCore’s managed ADOT pipeline leaves tracing to the application; host and secret ARN are not runtime environment variables.

Replace https://langfuse.example.com with your existing endpoint. To use Langfuse Cloud, explicitly pass its regional base URL, such as https://cloud.langfuse.com for EU or https://us.cloud.langfuse.com for US. Path prefixes are supported. Provide the base URL, without /api/public/otel; credentials, query parameters, and fragments in the URL are rejected. Repeat runs retain the previous host and secret unless you supply replacements; leaving either input blank keeps its saved value.

The exporter uses OTLP/HTTP with x-langfuse-ingestion-version: 4. Self-hosted installations must support that ingestion contract. Consult Langfuse’s OpenTelemetry integration and v4 migration guide when choosing an endpoint.

Use your normal AWS development credentials, such as an authenticated AWS profile selected with AWS_PROFILE. That identity needs secretsmanager:GetSecretValue on the selected secret, in addition to the permissions your agent normally needs for its model and tools. The generated execution-role grant covers the deployed agent; it does not grant permissions to your developer identity.

Terminal window
pnpm nx run my_agent:dev

The agent’s dev and serve targets run langfuse_dev.py through Uvicorn with automatic reload. It stores only the host and secret ARN, reads the keys from Secrets Manager, and initializes tracing before importing the agent. No deployed AppConfig application is needed to start local tracing. The assigned local port is preserved. Keys are never read from a local .env file or Langfuse environment variables.

Local development can run without Langfuse secret access. If its configuration or credentials cannot be loaded, startup logs a warning and the local agent continues without Langfuse export. Requests do not retry the secret lookup. Fix your AWS credentials, secret-read permission, or configuration, then restart dev/serve to enable tracing. Your agent still needs its normal model and tool permissions. Deployed agents continue to fail startup when their Langfuse credentials cannot be loaded.

Invoke the local agent using its generated chat client or HTTP endpoint. Both local and deployed invocations use the same Langfuse destination and session mapping. The agent’s local HTTP server keeps its normal behavior; the HTTPS requirement applies to the Langfuse destination. A laptop-only Langfuse endpoint such as http://localhost:3000 is not supported.

Builds, OpenAPI generation, and generated tests do not fetch Langfuse keys. The generated offline Python test checks both local configuration and AppConfig configuration with synthetic credentials and an in-memory exporter.

Build your workspace as described in the Python agent guide. The generator changes deployment files; it does not deploy them.

Invoke the local or deployed agent with a prompt that calls a tool. Open its trace detail view in the Langfuse UI and verify the invocation root, agent/model/tool children, and their input/output content. Select the model (generation) observation to check its token usage. Open the trace’s session to confirm the AgentCore session ID, then repeat a short request in that session to check flushing and grouping.

The application root retains the upstream AWS trace and parent IDs; the Langfuse SDK marks it as the logical application root even though the AWS service parent is not exported to Langfuse.

Session IDs between 33 and 200 characters appear unchanged in Langfuse. Longer IDs use their 64-character SHA-256 hex digest as the Langfuse session ID, so repeated requests still appear in the same session. This mapping changes only Langfuse grouping; the AgentCore session ID sent to the application is unchanged. A missing ID or one shorter than 33 characters gets a new UUID for that invocation. The generated client uses UUIDs within these limits.

The generator adds langfuse_telemetry.py and langfuse_dev.py beside the agent, a separate package/<agent>/langfuse_main.py entrypoint, and a Python exporter test. It wires the existing CDK construct to langfuse-observability.ts, copies the deployment entrypoint into the zip, and declares its dependencies. The stock ADOT launcher remains packaged.

The Langfuse entrypoint creates one provider before importing the agent. FastAPI’s overlapping tracing is disabled only in that process; native Strands spans use the same provider. The Langfuse SDK’s public observation API supplies the application root and session attributes. Invocation input/output capture is bounded to 1 MiB each; the root records content_truncated when that limit is exceeded.

The dependency set uses Langfuse 4.18.0 and ADOT 0.22.0. The vended OpenTelemetry pins match ADOT’s requirements, including API/SDK/HTTP exporter 1.45.1, and are held to preserve that compatibility. ADOT and Langfuse remain eligible for the repository’s regular dependency updates; check their compatibility and adjust the OpenTelemetry pins when upgrading. Starlette follows FastAPI’s dependency requirements.

Repeating the generator with the same inputs does not duplicate wiring or overwrite your runtime edits. It still honors your dependency-installation preference, so you can rerun it to retry a failed or deferred installation. Changing the host or secret updates both the local entrypoint and CDK configuration; restart local development, rebuild, and use the rollback-enabled deployment command to apply the change in both environments. If you edit either configuration or customize the local startup commands, the generator asks you to reconcile them before changing options. This prevents an option change from silently replacing custom wiring.

An earlier experimental setup without langfuse_dev.py must be reverted and regenerated with the updated generator. Preserve and reapply any customizations separately.

Revert the dedicated commit containing the Langfuse generator’s changes:

Terminal window
git revert <langfuse-setup-commit>

Review the revert for conflicts with subsequent agent changes. Other generators may have added usage-metric tags to the same array in packages/common/constructs/src/core/app.ts; preserve those tags when resolving the conflict. Remove the Langfuse tag (g79) only if no other agent still uses Langfuse, and preserve shared dependencies needed by remaining integrations.

Reinstall workspace dependencies, rebuild, then redeploy using the rollback-enabled deployment command. Removing the AppConfig entry also requires a resource replacement; do not use the default express command for this step. Reverting the complete setup restores the stock ADOT entrypoint and local startup commands, and removes the Langfuse wiring, files, dependency additions, runtime settings, and secret-read grant. Restart any running local dev process. Invoke the deployed agent with a new session and verify new application traces in CloudWatch.

The generator has no rollback flag. Keep unrelated changes out of the setup commit so reverting it does not remove them.

The existing secret remains yours to manage. Reverting the integration does not copy, delete, or move historical traces between backends. To enable Langfuse again, run the generator with the host and secret ARN.