logs

name	logs
description	OCaml Logs library patterns for structured logging. Use when Claude needs to: (1) Add logging to OCaml modules, (2) Create per-module log sources, (3) Use appropriate log levels, (4) Add structured tags to log messages

OCaml Logs Patterns

The logs library provides structured logging with per-module sources.

Module Setup

Every module that logs should create its own source:

let log_src = Logs.Src.create "project.module_name"
module Log = (val Logs.src_log log_src : Logs.LOG)

This is the standard idiom. Do NOT attempt to abstract or deduplicate this boilerplate.

Log Levels

Level	Function	Use Case
App	Log.app	Always shown to user (startup, completion)
Error	Log.err	Handled but critical errors
Warning	Log.warn	Potential issues, operation continues
Info	Log.info	State transitions, progress
Debug	Log.debug	Verbose debugging details

Basic Logging

Log.info (fun m -> m "Processing %d items" count);
Log.err (fun m -> m "Failed to connect: %s" reason);
Log.debug (fun m -> m "Request: %a" Request.pp req)

Structured Tags

Add context with tags for filtering/analysis:

Log.info (fun m ->
    m "Event received: %s" event_type
      ~tags:(Logs.Tag.add "channel_id" channel Logs.Tag.empty))

Reporter Setup (bin/)

In CLI applications, set up the reporter in bin/common.ml:

let setup_log style_renderer level =
  Fmt_tty.setup_std_outputs ?style_renderer ();
  Logs.set_level level;
  Logs.set_reporter (Logs_fmt.reporter ())

open Cmdliner

let setup_log =
  Term.(const setup_log
        $ Fmt_cli.style_renderer ()
        $ Logs_cli.level ())