/ 
Langertha-0.302
River stage zero No dependents
/ Langertha::Plugin::Langfuse

NAME

Langertha::Plugin::Langfuse - Langfuse observability plugin for any PluginHost

VERSION

version 0.302

SYNOPSIS

use Langertha::Chat;
use Langertha::Plugin::Langfuse;

my $langfuse = Langertha::Plugin::Langfuse->new(
    public_key => 'pk-lf-...',
    secret_key => 'sk-lf-...',
);

my $chat = Langertha::Chat->new(
    engine  => $engine,
    plugins => [$langfuse],
);

$chat->simple_chat('Hello!');
$langfuse->flush;

Or with sugar:

my $chat = Langertha::Chat->new(
    engine  => $engine,
    plugins => [Langfuse => {
        trace_name => 'my-chat',
        auto_flush => 1,
    }],
);

Environment variables LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and LANGFUSE_URL are auto-populated when not explicitly set.

DESCRIPTION

This plugin integrates any Langertha::Role::PluginHost (Langertha::Chat, Langertha::Embedder, Langertha::Raider) with Langfuse observability. It hooks into the standard plugin events to automatically create traces, generations, and spans.

Unlike Langertha::Role::Langfuse (which lives on the engine), this plugin works on any PluginHost and does not require engine-level configuration.

public_key

Langfuse project public key. Defaults to LANGFUSE_PUBLIC_KEY env var.

secret_key

Langfuse project secret key. Defaults to LANGFUSE_SECRET_KEY env var.

url

Langfuse API URL. Defaults to LANGFUSE_URL env var or https://cloud.langfuse.com.

enabled

Whether Langfuse integration is active. Defaults to true when both public_key and secret_key are non-empty.

trace_name

Name for the Langfuse trace created per chat session. Defaults to 'llm-call'.

user_id

Optional user ID passed to the Langfuse trace.

session_id

Optional session ID passed to the Langfuse trace.

tags

Optional tags passed to the Langfuse trace.

metadata

Optional metadata HashRef merged into the Langfuse trace.

auto_flush

When true, automatically flushes events after each plugin_after_llm_response. Defaults to false.

create_trace

my $trace_id = $plugin->create_trace(name => 'my-trace', input => {...});

Creates a trace event. Returns the trace ID. Called automatically by the plugin hooks, but can also be used manually.

create_generation

$plugin->create_generation(trace_id => $id, model => 'gpt-4o', ...);

Creates a generation event linked to a trace.

create_span

$plugin->create_span(trace_id => $id, name => 'tool-call', ...);

Creates a span event within a trace.

update_trace

$plugin->update_trace(id => $trace_id, output => 'result');

Updates a trace by upserting with the same ID.

flush

$plugin->flush;

Sends all batched events to the Langfuse ingestion API. Clears the batch after sending.

reset_trace

$plugin->reset_trace;

Resets the current trace state. Call this between independent chat sessions to start a new trace.

SEE ALSO

SUPPORT

Issues

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

CONTRIBUTING

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

AUTHOR

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

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.