Langfuse.Telemetry (Langfuse v0.1.0)

View Source

Telemetry events emitted by the Langfuse SDK.

The SDK emits telemetry events for HTTP requests and batch ingestion, enabling monitoring, logging, and metrics collection using the standard Erlang telemetry library.

Event Format

All events follow the telemetry convention:

  • Event name is a list of atoms
  • Measurements contain numeric values
  • Metadata contains contextual information

HTTP Events

  • [:langfuse, :http, :request, :start] - HTTP request initiated

    • Measurements: %{system_time: integer}
    • Metadata: %{method: atom, path: String.t, host: String.t}

  • [:langfuse, :http, :request, :stop] - HTTP request completed

    • Measurements: %{duration: integer} (native time units)

    • Metadata: %{method: atom, path: String.t, host: String.t, result: :ok | :error}

Ingestion Events

  • [:langfuse, :ingestion, :flush, :start] - Batch flush initiated

    • Measurements: %{batch_size: integer}
    • Metadata: %{}

  • [:langfuse, :ingestion, :flush, :stop] - Batch flush completed

    • Measurements: %{batch_size: integer, success_count: integer, error_count: integer}
    • Metadata: %{}

  • [:langfuse, :ingestion, :flush, :error] - Batch flush failed

    • Measurements: %{batch_size: integer}
    • Metadata: %{reason: term}

Prompt Events

  • [:langfuse, :prompt, :fetch, :start] - Prompt fetch initiated

    • Measurements: %{system_time: integer}

    • Metadata: %{name: String.t, version: integer | nil, label: String.t | nil}

  • [:langfuse, :prompt, :fetch, :stop] - Prompt fetch completed

    • Measurements: %{duration: integer}

    • Metadata: %{name: String.t, result: :ok | :error | :cache_hit}

Attaching Handlers

Attach your own handlers using :telemetry.attach/4:

:telemetry.attach(
  "my-langfuse-handler",
  [:langfuse, :http, :request, :stop],
  fn _event, measurements, metadata, _config ->
    duration_ms = System.convert_time_unit(measurements.duration, :native, :millisecond)
    Logger.info("Langfuse HTTP request took #{duration_ms}ms")
  end,
  nil
)

Or use the built-in debug logger:

Langfuse.Telemetry.attach_default_logger()

Summary

Functions

attach_default_logger(opts \\ [])

Attaches a default logger handler for all Langfuse telemetry events.

detach_default_logger()

Detaches the default logger handler.

events()

Returns all telemetry event names emitted by this library.

Functions

attach_default_logger(opts \\ [])

@spec attach_default_logger(keyword()) :: :ok | {:error, :already_exists}

Attaches a default logger handler for all Langfuse telemetry events.

Useful for debugging. Logs all events with the specified log level.

Options

  • :level - Log level. Defaults to :debug.

Examples

Langfuse.Telemetry.attach_default_logger()
# => :ok

Langfuse.Telemetry.attach_default_logger(level: :info)
# => :ok

Log Output

Events are logged in the format:

[Langfuse] langfuse.http.request.stop %{duration: 123456} %{method: :post, ...}

detach_default_logger()

@spec detach_default_logger() :: :ok | {:error, :not_found}

Detaches the default logger handler.

Examples

Langfuse.Telemetry.detach_default_logger()
# => :ok

events()

@spec events() :: [[atom()]]

Returns all telemetry event names emitted by this library.

Useful for attaching handlers to all events at once.

Examples

Langfuse.Telemetry.events()
# => [[:langfuse, :http, :request, :start], ...]

:telemetry.attach_many("my-handler", Langfuse.Telemetry.events(), &handler/4, nil)