LangfuseLangfuse Python SDK 4.15.4 · Python 3.10+
Dashboard
0%

Three tickets, and the card number

One program decides where traces and model calls go, and what is stripped before anything leaves. It runs three tickets, one with a card number in it.

Project files used on this pageThis lesson builds on a project from earlier lessons. The code below imports these files. Click a file to see its code, or follow the link to the lesson that wrote it. To run the code yourself, keep them in the same folder.
View the code here
privacy.py
import re

from langfuse.types import MaskOtelSpansResult, OtelSpanPatch

CARD = re.compile(r"\b\d(?:[ -]?\d){12,15}\b")


def mask_cards(*, params):
    patches = {}
    for span_id, span in params.spans.items():
        changed = {key: CARD.sub("[card]", value) for key, value in span.attributes.items() if isinstance(value, str) and CARD.search(value)}
        if changed:
            patches[span_id] = OtelSpanPatch(set_attributes=changed)
    return MaskOtelSpansResult(span_patches=patches)
shop_model.py
"""A stand-in chat model for the shop's support desk: no key, no network."""
import re


def reply(messages):
    """Answer the last message, and count words as tokens the way a chat model reports usage."""
    rules = messages[0]["content"].lower() if messages[0]["role"] == "system" else ""
    last = messages[-1]["content"]
    lookup = re.search(r"Lookup: (\S+) (.+)", last)
    if "refund" in last.lower():
        text = "Refunds need approval, so a person will review your request."
    elif lookup and "never share" in rules:
        text = "I cannot share order details."
    elif lookup and lookup.group(2) == "not found":
        text = f"I could not find order {lookup.group(1)}. Please check the number."
    elif lookup:
        text = f"Order {lookup.group(1)} {lookup.group(2)}."
    else:
        text = "Could you send your order number?"
    if "thank" in rules:
        text = "Thanks for waiting. " + text
    used = sum(len(message["content"].split()) for message in messages)
    return text, {"input": used, "output": len(text.split())}
support_desk.py
"""The shop's support desk as a traced service."""
import re

from langfuse import get_client, observe, propagate_attributes

ORDERS = {"A17": "shipped on 3 March"}
FALLBACK = "You answer customers of a small online shop in one short sentence."
model = None  # an OpenAI-compatible client, set by the program that runs the desk


@observe(name="lookup-order", as_type="tool")
def lookup_order(order_id):
    status = ORDERS.get(order_id, "not found")
    if status == "not found":
        get_client().update_current_span(level="WARNING", status_message=f"no order {order_id}")
    return status


@observe(name="answer-ticket", as_type="agent")
def answer(ticket):
    prompt = get_client().get_prompt("desk-system", fallback=FALLBACK)
    order = re.search(r"[A-Z]\d{2}", ticket)
    facts = f"\nLookup: {order.group()} {lookup_order(order.group())}" if order else ""
    messages = [{"role": "system", "content": prompt.compile()}, {"role": "user", "content": ticket + facts}]
    response = model.chat.completions.create(model="shop-model", messages=messages,
                                             name="write-reply", langfuse_prompt=prompt)
    return response.choices[0].message.content


def handle(ticket_number, ticket, customer, chat):
    langfuse = get_client()
    trace_id = langfuse.create_trace_id(seed=ticket_number)
    with langfuse.start_as_current_observation(name="support-ticket", input=ticket,
                                               trace_context={"trace_id": trace_id}) as span:
        with propagate_attributes(user_id=customer, session_id=chat, tags=["desk"]):
            text = answer(ticket)
        span.update(output=text)
    return text


def record_feedback(ticket_number, helpful, comment=None):
    langfuse = get_client()
    langfuse.create_score(
        trace_id=langfuse.create_trace_id(seed=ticket_number), score_id=f"{ticket_number}-feedback",
        name="user-feedback", value=1 if helpful else 0, data_type="BOOLEAN", comment=comment,
    )
local_langfuse.py
"""A stand-in for the Langfuse server, on your own machine.

The Langfuse SDK sends observations to /api/public/otel/v1/traces and uses a
REST API for scores, prompts and datasets. This server answers those requests
on 127.0.0.1 and keeps what it receives in lists you can print. Given a model
function, it also answers like OpenAI's chat API. start() blocks every
connection to another computer for the rest of the program.
"""
import json
import socket
import threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import parse_qs, unquote, urlparse

from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import ExportTraceServiceRequest

SPANS, SCORES, REQUESTS = [], [], []  # observations, scores, "METHOD /path" of each request
PROMPTS, DATASETS = {}, {}             # prompt name -> its versions, dataset name -> dataset
MODEL = None                           # answers /v1/chat/completions when set
NOW = "2026-03-03T09:00:00Z"


def _value(v):
    kind = v.WhichOneof("value")
    if kind == "array_value":
        return [_value(item) for item in v.array_value.values]
    return getattr(v, kind) if kind else None


def _spans(body):
    request = ExportTraceServiceRequest()
    request.ParseFromString(body)
    for resource in request.resource_spans:
        for scope in resource.scope_spans:
            for span in scope.spans:
                SPANS.append({
                    "name": span.name, "id": span.span_id.hex(), "trace": span.trace_id.hex(),
                    "parent": span.parent_span_id.hex(), "scope": scope.scope.name,
                    "attributes": {a.key: _value(a.value) for a in span.attributes},
                })
    return {}


def _scores(batch):
    for event in batch:
        if event["type"] == "score-create":
            SCORES.append(event["body"])
    return {"successes": [{"id": e["id"], "status": 201} for e in batch], "errors": []}


def _prompt(name, query, body):
    versions = PROMPTS.setdefault(name, [])
    if body is not None:  # a new version: it takes "latest" and any labels it asks for
        labels = body.get("labels", []) + ["latest"]
        for old in versions:
            old["labels"] = [label for label in old["labels"] if label not in labels]
        versions.append({"name": name, "type": body.get("type", "text"), "prompt": body["prompt"],
                         "config": body.get("config") or {}, "labels": labels, "tags": [],
                         "version": len(versions) + 1})
        return versions[-1]
    if "version" in query:
        return versions[int(query["version"]) - 1]
    label = query.get("label", "production")
    return next(v for v in versions if label in v["labels"])


def _relabel(path, body):
    name, _, version = path.split("/")[-3:]
    versions = PROMPTS[unquote(name)]
    for old in versions:
        old["labels"] = [label for label in old["labels"] if label not in body["newLabels"]]
    versions[int(version) - 1]["labels"] += body["newLabels"]
    return versions[int(version) - 1]


def _dataset(path, query, body):
    if path == "/api/public/v2/datasets":
        DATASETS[body["name"]] = {"id": body["name"], "name": body["name"], "items": [],
                                  "metadata": body.get("metadata"), "projectId": "local",
                                  "createdAt": NOW, "updatedAt": NOW}
        return DATASETS[body["name"]]
    if path.startswith("/api/public/v2/datasets/"):
        return DATASETS[unquote(path.rsplit("/", 1)[1])]
    if path == "/api/public/dataset-items" and body is not None:
        dataset = DATASETS[body["datasetName"]]
        item = {"id": body.get("id") or f"item-{len(dataset['items']) + 1}", "status": "ACTIVE",
                "input": body.get("input"), "expectedOutput": body.get("expectedOutput"),
                "metadata": body.get("metadata"), "sourceTraceId": body.get("sourceTraceId"),
                "datasetId": dataset["id"], "datasetName": dataset["name"],
                "createdAt": NOW, "updatedAt": NOW, "mediaReferences": []}
        dataset["items"].append(item)
        return item
    if path == "/api/public/dataset-items":
        items = DATASETS[query["datasetName"]]["items"]
        return {"data": items, "meta": {"page": 1, "limit": 50, "totalItems": len(items), "totalPages": 1}}
    return {"id": "run-item", "datasetRunId": body["runName"], "datasetRunName": body["runName"],
            "datasetItemId": body["datasetItemId"], "traceId": body["traceId"],
            "observationId": body.get("observationId"), "createdAt": NOW, "updatedAt": NOW}


def _chat(body):
    text, usage = MODEL(body["messages"])
    return {"id": "chatcmpl-1", "object": "chat.completion", "created": 0, "model": body["model"],
            "choices": [{"index": 0, "finish_reason": "stop", "message": {"role": "assistant", "content": text}}],
            "usage": {"prompt_tokens": usage["input"], "completion_tokens": usage["output"],
                      "total_tokens": usage["input"] + usage["output"]}}


class Handler(BaseHTTPRequestHandler):
    def _handle(self):
        url = urlparse(self.path)
        query = {key: values[0] for key, values in parse_qs(url.query).items()}
        raw = self.rfile.read(int(self.headers.get("Content-Length") or 0))
        body = json.loads(raw) if raw and "json" in self.headers.get("Content-Type", "") else None
        REQUESTS.append(f"{self.command} {url.path}")
        try:
            if url.path.endswith("/otel/v1/traces"):
                return self._reply(200, _spans(raw))
            if url.path == "/api/public/ingestion":
                return self._reply(207, _scores(body["batch"]))
            if url.path == "/api/public/projects":
                return self._reply(200, {"data": [{"id": "local", "name": "shop-desk", "metadata": {},
                                                   "organization": {"id": "local", "name": "local"}}]})
            if url.path.startswith("/api/public/v2/prompts/") and self.command == "PATCH":
                return self._reply(200, _relabel(url.path, body))
            if url.path.startswith("/api/public/v2/prompts"):
                name = body["name"] if body else unquote(url.path.rsplit("/", 1)[1])
                return self._reply(200, _prompt(name, query, body))
            if "dataset" in url.path:
                return self._reply(200, _dataset(url.path, query, body))
            if url.path.endswith("/chat/completions") and MODEL:
                return self._reply(200, _chat(body))
        except (KeyError, StopIteration):
            pass
        self._reply(404, {"message": f"not found: {url.path}"})

    do_GET = do_POST = do_PATCH = _handle

    def _reply(self, code, data):
        self.send_response(code)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(json.dumps(data).encode())

    def log_message(self, *args):
        pass


def _local_only():
    """Refuse to look up or connect to any other computer, so nothing leaves by mistake."""
    lookup, connect = socket.getaddrinfo, socket.socket.connect

    def guarded_lookup(host, *args, **kwargs):
        if host not in ("127.0.0.1", "localhost", "::1"):
            raise ConnectionRefusedError(f"blocked a connection to {host}: this lab stays on your machine")
        return lookup(host, *args, **kwargs)

    def guarded_connect(sock, address):
        if isinstance(address, tuple) and address[0] not in ("127.0.0.1", "::1"):
            raise ConnectionRefusedError(f"blocked a connection to {address[0]}: this lab stays on your machine")
        return connect(sock, address)

    socket.getaddrinfo, socket.socket.connect = guarded_lookup, guarded_connect


def start(model=None):
    """Start the server in the background and return its address."""
    global MODEL
    _local_only()
    MODEL = model
    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
    threading.Thread(target=server.serve_forever, daemon=True).start()
    return f"http://127.0.0.1:{server.server_address[1]}"


def tree(*fields):
    """Print the observations received so far, each under its parent, with any fields asked for."""
    ids = {span["id"] for span in SPANS}

    def walk(span, depth):
        attributes = span["attributes"]
        line = "  " * depth + f"{span['name']} ({attributes.get('langfuse.observation.type', 'span')})"
        for field in fields:
            line += f"  {field}={attributes.get('langfuse.observation.' + field)!r}"
        print(line)
        for child in SPANS:
            if child["parent"] == span["id"]:
                walk(child, depth + 1)

    for root in [span for span in SPANS if span["parent"] not in ids]:
        walk(root, 0)

This is the only file that knows about servers and keys. The desk module knows none of it.

Exampleapp.py
from langfuse import Langfuse
from langfuse.openai import OpenAI

import local_langfuse
import support_desk
from privacy import mask_cards
from shop_model import reply

url = local_langfuse.start(model=reply)
langfuse = Langfuse(public_key="pk-lf-local", secret_key="sk-lf-local", base_url=url,
                    environment="production", release="2026.03.1", mask_otel_spans=mask_cards)
support_desk.model = OpenAI(base_url=f"{url}/v1", api_key="not-a-real-key")
langfuse.create_prompt(name="desk-system", prompt=support_desk.FALLBACK, labels=["production"])

The client carries the environment and the version of the deployment, so traces can be filtered by either, and the masking function from part 4, which runs on everything exported. The desk's model client is set here too, which is how the tests point it somewhere else.

Exampleapp.py, continued
tickets = [("ticket-1042", "Where is my order A17?"),
           ("ticket-1043", "Is B22 on its way? Card 4111 1111 1111 1111 was charged."),
           ("ticket-1044", "I want a refund for A17")]
for number, text in tickets:
    print(number, "->", support_desk.handle(number, text, customer="cust-42", chat="chat-0042"))
support_desk.record_feedback("ticket-1043", helpful=False, comment="B22 is on my receipt")

langfuse.flush()
local_langfuse.tree()
print([(s["name"], s["attributes"]["langfuse.observation.status_message"]) for s in local_langfuse.SPANS
       if s["attributes"].get("langfuse.observation.level") == "WARNING"])
print("card exported:", "4111" in str([s["attributes"] for s in local_langfuse.SPANS]))
Example
python app.py

Three traces, each rooted in support-ticket with the model call and any lookup under it. The B22 ticket carries the warning. The card number reached the desk and was replaced before export, so the last line prints False.

Three tickets through the traced support desk
support-ticketorder idthenticketmay hold a cardanswer-ticketagent, prompt from Langfuselookup-ordertool, WARNING when missingwrite-replygeneration via langfuse.openaimask_cardsmask_otel_spanslocal_langfusewhat was sentrecord_feedbackscore by ticket id
Hover or tap a piece to see what it is and which lesson built it.
Follow a ticket

Pick one to watch it run, step by step.

Click through the three tickets in the drawing: the answer, the warning and the masked card each take a different path through the same desk.

Try it yourself
  • Add a fourth ticket with an email address and mask that too.
  • Set environment="staging" and find it on the observations.
  • Remove mask_otel_spans and watch the last line turn to True.

Slow is fine. Stopping is the only problem.