Named inputs in @observe

[rusih100]

Problem

The @observe decorator is really convenient. Instead of managing observations manually with a context manager

def answer(query: str, lang: str, client: OpenAI) -> Response:
    with langfuse.start_as_current_observation(name="answer") as span:
        span.update(input={"query": query, "lang": lang})
        ...

you add one line above the function and keep its body clean.

But the traces it produces are hard to work with. Arguments are recorded as {"args": [...], "kwargs": {...}}:

@observe()
def answer(query: str, lang: str, client: OpenAI) -> Response: ...

answer("how do I return an item?", "en", client=openai_client)

{
  "args": ["how do I return an item?", "en"],
  "kwargs": {"client": "<OpenAI object>"}
}

In practice this gets in the way:

• Positional arguments lose their names. The UI shows args[0] and args[1], and you have to open the code to understand what they are.
• The same call looks different depending on how it was made. answer("q", "en") and answer(query="q", lang="en") produce different structures, which makes filtering traces and building datasets from them harder.
• Service objects end up in the trace: clients, sessions, connections. That is how an Azure OpenAI key leaked in Field-level selection for input/output filtering in decorator instead of using update_current_observation/trace #3524.

The workaround is capture_input=False plus a manual update_current_span(input=...), but then every function gets tracing code again and the decorator loses its point. The global mask doesn't help either: it receives the already-built {"args", "kwargs"} and doesn't know the parameter names.

Proposal

Add a named_inputs flag. With it, the decorator binds arguments to the function signature via inspect.signature(func).bind(...) and records input with names:

@observe(named_inputs=True)
def answer(query: str, lang: str, client: OpenAI) -> Response: ...

{"query": "how do I return an item?", "lang": "en", "client": "<OpenAI object>"}

It can be enabled globally with LANGFUSE_OBSERVE_DECORATOR_NAMED_INPUTS, the same way capture_input works today. It's off by default, so nothing changes for existing users.

A nice side effect: once inputs have names, the existing mask can drop parameters like client or session globally. No separate filtering mechanism is needed.

Details

• self and cls are excluded from input, as they are now.
• If binding fails, input is recorded in the current format.
• Works for sync, async and generator functions.
• Python only: parameter names aren't available at runtime in JS.

Open question: whether to record default values. I'd record only the arguments actually passed, so the trace reflects the real call.

Happy to open a PR.

---

English isn't my first language, so I used AI to help write this up. I've reviewed everything and stand behind the proposal.

[rusih100]

Opened a PR with the implementation: langfuse/langfuse-python#2069