/ 
Langertha-Knarr-1.102
/ Langertha::Knarr::Handler::Tracing

NAME

Langertha::Knarr::Handler::Tracing - Decorator handler that records every request as a Langfuse trace

VERSION

version 1.102

SYNOPSIS

use Langertha::Knarr::Tracing;
use Langertha::Knarr::Handler::Tracing;

my $tracing = Langertha::Knarr::Tracing->new(config => $config);
$handler = Langertha::Knarr::Handler::Tracing->new(
    wrapped => $handler,
    tracing => $tracing,
);

DESCRIPTION

Decorator handler that opens a Langfuse trace + generation around every chat or stream request and closes it with the assistant text once the inner handler resolves (or fails). Streaming requests accumulate every delta into a single output before closing the trace, so the Langfuse view shows the full assembled response, with the token usage the backend reported on its stream ("usage" in Langertha::Knarr::Stream).

The generation's model is the model the backend reported answering with ("upstream_model" in Langertha::Knarr::Response, "upstream_model" in Langertha::Knarr::Stream), which can be more concrete than the one asked for. When a handler labeled the answer with another name -- Langertha::Knarr::Handler::Router answers under the configured model -- that name is recorded as configured_model in the generation's metadata. Without a reported model the generation gets the label, and a stream without either the model the client asked for.

knarr start mounts this automatically when the config supplies Langfuse credentials.

A raw passthrough request that Langertha::Knarr answers through the handler chain after the upstream refused the client's key (see "raw_passthrough" in Langertha::Knarr) is traced here only, once, with the refusing status as passthrough_fallback in the trace's metadata.

wrapped

Required. The inner Langertha::Knarr::Handler being decorated. The attribute is named wrapped rather than inner because Moose imports an inner() keyword used for augmented methods.

tracing

Required. A Langertha::Knarr::Tracing instance (or any object implementing start_trace / end_trace).

engine_label

Optional. A string injected into the trace metadata's engine field. Defaults to ref($self->wrapped).

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha-knarr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.