Hcs.Log

hcs · API reference

Structured request logging helpers.

Use this module to configure request logs, combine loggers, set minimum log levels, generate request IDs, and format request lifecycle events.

Logging module for HCS HTTP library.

Provides structured logging for HTTP events including requests, responses, connections, and errors. The module is runtime-agnostic and uses a callback-based approach for flexibility.

Usage

(* Use built-in stderr logger *)
let logger = Hcs.Log.stderr ()

(* Use null logger (no output) *)
let logger = Hcs.Log.null

(* Use custom logger *)
let logger =
  Hcs.Log.custom (fun level msg ->
      match level with
      | Hcs.Log.Error -> Printf.eprintf "[ERROR] %s\n%!" msg
      | _ -> Printf.printf "[%s] %s\n%!" (Hcs.Log.level_to_string level) msg)

Types

type level = 
  | Debug (* Detailed debugging information *)
  | Info (* General information about operations *)
  | Warn (* Warning conditions *)
  | Error (* Error conditions *)

Log levels

type http_method = 
  | GET
  | POST
  | PUT
  | DELETE
  | PATCH
  | HEAD
  | OPTIONS
  | CONNECT
  | TRACE
  | Other of string

HTTP method for logging (simplified)

type event = 
  | Request_start of {
    id : string;
    meth : http_method;
    uri : string;
    headers : (string * string) list;
  } (* Request started *)
  | Request_end of {
    id : string;
    status : int;
    duration_ms : float;
    body_size : int option;
  } (* Request completed *)
  | Connection_open of {
    host : string;
    port : int;
    protocol : string; (* "http/1.1" or "h2" *)
  } (* Connection opened *)
  | Connection_close of {
    host : string;
    port : int;
    reason : string;
  } (* Connection closed *)
  | Connection_reuse of {
    host : string;
    port : int;
  } (* Connection reused from pool *)
  | Tls_handshake of {
    host : string;
    protocol : string; (* TLS version *)
    cipher : string option;
  } (* TLS handshake completed *)
  | Retry of {
    id : string;
    attempt : int;
    reason : string;
    delay_ms : float option;
  } (* Request retry *)
  | Redirect of {
    id : string;
    from_uri : string;
    to_uri : string;
    status : int;
  } (* Following redirect *)
  | Error of {
    id : string option;
    error : string;
    context : string option;
  } (* Error occurred *)
  | Custom of {
    name : string;
    data : (string * string) list;
  } (* Custom event *)

Log events - structured events that can be logged

type logger = level -> event -> unit

Logger function type

Level operations

val level_to_string : level -> string

Convert level to string

val level_of_string : string -> level option

Parse level from string

val level_to_int : level -> int

Compare log levels (for filtering)

val level_gte : level -> level -> bool

HTTP method operations

val method_to_string : http_method -> string

val method_of_h1 : Method.t -> http_method

Event formatting

val event_to_string : event -> string

Format event as a human-readable string

val event_to_json : event -> string

Format event as JSON string

Built-in Loggers

val null : logger

Null logger - discards all events

val stderr : ?min_level:level -> ?json:bool -> unit -> logger

Stderr logger with optional minimum level filter

val stdout : ?min_level:level -> ?json:bool -> unit -> logger

Stdout logger with optional minimum level filter

val custom : (level -> string -> unit) -> logger

Custom logger from a simple callback

val custom_json : (level -> string -> unit) -> logger

Custom logger with JSON output

val combine : logger list -> logger

Combine multiple loggers

val with_min_level : level -> logger -> logger

Filter logger by minimum level

Request ID generation

val request_id_counter : int ref

Counter for unique request IDs

val generate_request_id : unit -> string

Generate a unique request ID