/ 
Langertha-Knarr-0.007
River stage zero No dependents
/ Langertha::Knarr::RequestLog

NAME

Langertha::Knarr::RequestLog - Local disk logging of proxy requests

VERSION

version 0.007

SYNOPSIS

use Langertha::Knarr::RequestLog;

my $rlog = Langertha::Knarr::RequestLog->new(config => $config);

my $handle = $rlog->start_request(
  model    => 'gpt-4o',
  format   => 'openai',
  engine   => 'Langertha::Engine::OpenAI',
  path     => '/v1/chat/completions',
  stream   => 1,
  messages => \@messages,
  params   => \%params,
);

# ... handle request ...

$rlog->end_request($handle,
  output => $response_text,
  usage  => { input => 100, output => 50, total => 150 },
);

DESCRIPTION

Records every proxy request as a JSON log entry on local disk. Supports two modes: JSONL (one line per request, append to a single file) and per-request JSON files in a directory.

When both log_file and log_dir are set, both are written. When neither is set, all methods are no-ops.

Log file/directory are read from the config file's logging: section or from the KNARR_LOG_FILE and KNARR_LOG_DIR environment variables. The module strips surrounding quotes from environment variable values.

config

The Langertha::Knarr::Config object. Required. Provides log_file and log_dir settings.

log_file

Path to the JSONL log file. One JSON object per line, suitable for tail -f knarr.jsonl | jq. Resolved from logging.file in config or KNARR_LOG_FILE environment variable.

log_dir

Path to a directory for per-request JSON files. Each request produces a pretty-printed {timestamp}_{format}_{model}.json file. Resolved from logging.dir in config or KNARR_LOG_DIR environment variable.

start_request

my $handle = $rlog->start_request(
  model    => $model_name,
  format   => 'openai',
  engine   => $engine_class,
  path     => '/v1/chat/completions',
  stream   => 1,
  messages => \@messages,
  params   => \%params,
);

Begins collecting data for a request. Returns a handle (hashref) that must be passed to "end_request". Returns undef when logging is disabled.

end_request

$rlog->end_request($handle,
  output => $response_text,
  usage  => { input => 100, output => 50, total => 150 },
);

# On error:
$rlog->end_request($handle, error => "Something went wrong");

Completes the log entry with output, usage, duration and writes it to disk. Does nothing when $handle is undef (logging was disabled at start).

SEE ALSO

SUPPORT

Issues

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

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.