LANGFUSE LAB · THE TRACE BEHIND THE BUTTON

See what your agent actually did.

Already connected? Learn the basics and read a trace → Download lab instructions (.md)

REAL REHEARSAL VERIFIEDThe native Lovable app delivered a run independently matched in Langfuse: six observations and 948 reported tokens. Follow the simple three-setting route or see the actual trace tree. Your own project still needs its own live check.

One app action, one trace. Inspect the model calls, permitted tools, failures and reported usage in your own project.

VISIBLE IN PART 1 · BUILT OUT IN PART 4You can show a prepared trace during the first hour. Configure the project before the session, or complete this integration in Part 4 after the app works. The static guide never sends telemetry.

The simple setup: three values, one prompt, one check.

Recommended student path: use your own Langfuse Cloud Hobby organization/project when you do not already have a reachable instance. No Docker setup is needed for that route.

Choose your instance. Use your own working self-hosted installation or Langfuse Cloud. Copy the instance base URL, not a project/trace page path. It must be reachable from the app backend; a hosted builder cannot reach a Langfuse server bound only to your laptop loopback.
Add three server values. Store LANGFUSE_BASE_URL, LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY in the app's backend secrets/environment settings. Never enter real keys in this static training page or a builder chat.
Give the builder the integration prompt. Download the Langfuse wiring instructions (.md). One-time code instrumentation is required; the builder/coding agent does it using your existing model integration.
Run one actual action. Open its exact trace in your project. Only independent readback earns a verified result.

The same three values work for a compatible self-hosted or Cloud setup. Code still needs the correct SDK/runtime integration and a reachable approved destination; the values alone do not instrument an app.

Where do I add those three values?

Lovable · use the existing native AI app

Use the project's backend Secrets area and the prompt above. Keep the current Lovable-provided model. The agent instruments the actual server action; a personal chat connector is not runtime tracing. Confirm backend/AI feature permissions and available credits separately.

How Lovable connects external APIs → · Backend and Secrets overview →

Base44 · use backend functions and secrets

Confirm your account supports server-side functions. Give the integration prompt to the builder and store project credentials in backend secrets. A client-only app cannot protect the secret key or safely implement the exporter; do not put it in a public settings field.

Base44 developer documentation →

v0 · server environment variables

Add the three values to the app's server environment. Ask v0 to instrument its server route/action and keep secrets out of client bundles. Do not prefix secret values with NEXT_PUBLIC_. Apply the platform's required restart/redeployment so the server reads the new environment.

v0 environment-variable guide →

Codex / code · private runtime configuration

Ask Codex to apply the same wiring prompt to the actual server code. Keep values in an ignored private env file or secret store. The existing Python Studio uses the telemetry table and --secrets mechanism documented below, so reuse its Observer rather than installing another exporter.

Existing runtime instrumentation map →

CAN THE FREE CLOUD PLAN WORK FOR THIS COURSE?

Checked 31 October 2026: Hobby is free with no card, includes 50,000 units/month, 30-day data access and two users. Units are not the same as traces; usage depends on the recorded observations. Use an individual learner project rather than inviting an entire class into one two-user project. Recheck eligibility, quotas and region before the event; model usage is a separate cost.

Current plans and limits →

EXPLORE THE IDEA · SYNTHETIC ILLUSTRATION

Example

No model call, permission decision, cloud action or telemetry export is performed by this illustration. Use your actual app and receipts for acceptance.

1. Create your own installation and project

Follow the official Docker Compose guide for a local installation. Review the selected repository revision, compose services, required secrets, port bindings and resource use before starting it. Record the revision you used; do not expose the upstream sample unchanged as a public service. A container runtime is additional to the basic app setup.

The official flow clones the Langfuse repository, changes its compose secrets, starts the reviewed compose stack and opens its web UI. Create your own user, organization and project, then create project API keys. Keep them in a private secrets file. You can also use your own existing hosted project; no account or credits are supplied by this workshop.

Langfuse source ↗ · Compose prerequisites ↗

Local installation commands · review before starting

From the workshop checkout, create a new ignored private clone. This downloads source, not an entitlement or a ready-made project.

git clone https://github.com/langfuse/langfuse.git local/private/langfuse-home
cd local/private/langfuse-home
git rev-parse HEAD
docker compose config --services

Record the revision for replay. Review the compose file and official instructions: change its default secrets privately, review published ports, keep local access bound to your intended interface and verify native image/platform support. Do not paste the resolved full compose configuration into shared logs because it can contain secrets. Only after that review, start your own compose project:

docker compose up

Open its configured UI (the upstream local default is localhost:3000), sign up, create an organization/project and your own project keys. Ctrl-C stops the owned foreground stack. To stop that same project later, run docker compose stop in its directory. Do not delete volumes if you want to keep traces. Follow the recorded revision and official upgrade procedure for later changes.

2. Enable the existing Observer

The local Studio already instruments real agent work; no extra Langfuse SDK or collector daemon is needed for this path. Install the frozen studio extra. Merge the following into the existing private model TOML, replacing its telemetry table rather than adding a duplicate:

[telemetry]
enabled = true
capture_content = false
service_name = "opsdesk-agent"
langfuse_endpoint = "http://127.0.0.1:3000"
allowed_hosts = ["127.0.0.1"]
langfuse_public_key_env = "LANGFUSE_PUBLIC_KEY"
langfuse_secret_key_env = "LANGFUSE_SECRET_KEY"

This example is for a host-run Studio and host-accessible local Langfuse UI. For your own HTTPS instance, use its base URL and exact allowed host. Container-to-host addressing differs; 127.0.0.1 inside a container is that container, not your laptop. Do not weaken destination validation to make it connect.

3. Keep your project keys private

Create a private 0600 env file with only the required key names and your own values. Use an editor or private secret store; do not paste values into command history, the app browser, a public repository or this guide.

# File structure only — replace placeholders privately; do not run with these values.
LANGFUSE_PUBLIC_KEY="<YOUR_PROJECT_PUBLIC_KEY>"
LANGFUSE_SECRET_KEY="<YOUR_PROJECT_SECRET_KEY>"

4. Restart the owned app with a fresh receipt directory

chmod 600 local/private/home/studio.toml local/private/home/keys.env
PYTHONPATH=src .venv/bin/python -m agent_workshop.studio --config local/private/home/studio.toml --secrets local/private/home/keys.env --output local/private/home/observed-01 --port 8770

The file must also contain any configured model key reference required by your gateway. Stop your own previous foreground server first. Do not stop a shared listener or overwrite an old receipt folder.

5. Run one action, then inspect the three receipts

Open your app/reference and run one synthetic investigation with the configured real model.
Inspect the local run ID, session and trace ID, model outcome, reported tokens and exporter result.
Click the exact trace readback control in that same browser session. Independently find that exact trace in your own Langfuse project.
Open its observations: agent root, authorization, each actual generation and each permitted tool. A change-intent policy path should have no generation.

The existing exporter uses OTLP HTTP/protobuf at /api/public/otel/v1/traces, server-side project Basic authentication and the version-4 ingestion header. Configure the base URL only in Studio; it appends the trace path. See the official OTel integration.

What should I learn from the trace?

Did the model actually call the tool, and did that handler succeed?
Which calls consumed time and reported tokens?
Did the policy stop the change before inference?
Was telemetry delivered and independently read back, or merely recorded locally?

Metadata-only export deliberately excludes prompt/answer/tool text. It cannot explain hidden reasoning or automatically evaluate answer quality. Cost is an estimate only when usage and matching rates are known. Langfuse readback does not prove APM/log ingestion or enforce a permission.

My trace is missing

Check local recording first, then exporter status, then exact project/session/trace readback. For 401/403 diagnose the responding service and destination/auth binding without printing credentials. For an ingestion delay, perform a bounded later readback; do not rerun paid inference automatically. A healthy UI is not an ingestion check.

Continue the full observability lab → Download the instrumentation guide