{"id":20135871,"url":"https://github.com/hcarty/ezlogs-cli","last_synced_at":"2026-01-29T23:05:57.611Z","repository":{"id":141495808,"uuid":"239891469","full_name":"hcarty/ezlogs-cli","owner":"hcarty","description":"Ready-to-eat logging configuration using Cmdliner and Logs","archived":false,"fork":false,"pushed_at":"2021-05-19T04:59:16.000Z","size":34,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T17:47:20.059Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hcarty.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-12T00:10:34.000Z","updated_at":"2024-11-04T23:47:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"e10205ad-bdd3-43ac-ad1e-226357d51630","html_url":"https://github.com/hcarty/ezlogs-cli","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hcarty/ezlogs-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcarty%2Fezlogs-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcarty%2Fezlogs-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcarty%2Fezlogs-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcarty%2Fezlogs-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hcarty","download_url":"https://codeload.github.com/hcarty/ezlogs-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcarty%2Fezlogs-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28889863,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T21:06:44.224Z","status":"ssl_error","status_checked_at":"2026-01-29T21:06:42.160Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T21:16:53.919Z","updated_at":"2026-01-29T23:05:57.605Z","avatar_url":"https://github.com/hcarty.png","language":"OCaml","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Structured logging for OCaml using [Logs] + [Cmdliner]\n\nThis repository defines a few libraries:\n- `ecs` provides field definitions for composing JSON documents which conform\n  to the Elastic Common Schema ([ECS])\n- `ezlogs-cli` provides convenient [Cmdliner] terms to ease initializing [Logs]\n  in an application\n- `ezlogs-cli-lwt` is like `ezlogs-cli` with the exception that it initializes\n  logging in a [Lwt] friendly way.\n\n`ezlogs-cli` and `ezlogs-cli-lwt` can initialize [Logs] to produce unstructured\n(`line`) or structured (`json`) log output.  Structured output uses the `ecs`\nlibrary to generate JSON output with one JSON object per log message.\n\n## Examples\n\nLet's load up the library and set a logging level.\n```ocaml\n# #require \"ecs\";;\n# #require \"ezlogs-cli\";;\n# #require \"ezlogs-cli-lwt\";;\n# Logs.set_level (Some Info);;\n- : unit = ()\n```\n\nAnd we'll define a fixed timestamp to use so the output here in the README is\nstable over time.\n```ocaml\n# let timestamp = Ptime.of_float_s 2590779494.386 |\u003e Option.get;;\nval timestamp : Ptime.t = \u003cabstr\u003e\n# let tags = Ecs.tags_of_list [Base (Timestamp timestamp)];;\nval tags : Logs.Tag.set = \u003cabstr\u003e\n```\n\nSetup a logger with simple, unstructured logging and give it a try!\n```ocaml\n# Logs.set_reporter (Ezlogs_cli.Line_output.reporter Fmt.stdout);;\n- : unit = ()\n# Logs.info (fun m -\u003e m \"Hello from the future\" ~tags);\n2052-02-05T20:58:14.386Z [INFO] Hello from the future\n- : unit = ()\n```\n\n[ECS] compliant JSON logging is also an option if we pick the correct reporter.\n```ocaml\n# Logs.set_reporter (Ezlogs_cli.Json_output.reporter Fmt.stdout);;\n- : unit = ()\n# Logs.info (fun m -\u003e m \"Hello from the future\" ~tags);;\n{\"@timestamp\":\"2052-02-05T20:58:14.386Z\",\"ecs.version\":\"1.5.0\",\"log.level\":\"info\",\"log.logger\":\"application\",\"message\":\"Hello from the future\"}\n- : unit = ()\n```\n\nWe can add fields to include more details.\n```ocaml\n# let error_tags = Ecs.add_tag (Error (Code \"failure-101\")) tags;;\nval error_tags : Logs.Tag.set = \u003cabstr\u003e\n# Logs.err (fun m -\u003e m \"There was a failure\" ~tags:error_tags);;\n{\"@timestamp\":\"2052-02-05T20:58:14.386Z\",\"ecs.version\":\"1.5.0\",\"error.code\":\"failure-101\",\"log.level\":\"error\",\"log.logger\":\"application\",\"message\":\"There was a failure\"}\n- : unit = ()\n```\n\nEvent logs can be quite descriptive.\n```ocaml\n# let file_uri = Uri.of_string \"file:///home/ecs/newfile.ext\";;\nval file_uri : Uri.t = \u003cabstr\u003e\n# let event_tags =\n    Ecs.add_tags [\n      Ecs.service [Name \"file_saver\"; Version \"git commit hash\"];\n      Ecs.event [Category [File]; Kind Event; Outcome Success; Type [Creation]; Url file_uri];\n      Ecs.file [Hash (Md5 \"NOT A HASH\")];\n      Ecs.trace [Trace_id \"unique 'global' id\"; Transaction_id \"unique 'local' id\"];\n    ]\n    tags;;\nval event_tags : Logs.Tag.set = \u003cabstr\u003e\n# Logs.info (fun m -\u003e m \"Not sure this message is necessary\" ~tags:event_tags);;\n{\"@timestamp\":\"2052-02-05T20:58:14.386Z\",\"ecs.version\":\"1.5.0\",\"event.category\":[\"file\"],\"event.kind\":\"event\",\"event.outcome\":\"success\",\"event.type\":[\"creation\"],\"event.url\":\"file:///home/ecs/newfile.ext\",\"file.hash.md5\":\"NOT A HASH\",\"log.level\":\"info\",\"log.logger\":\"application\",\"message\":\"Not sure this message is necessary\",\"service.name\":\"file_saver\",\"service.version\":\"git commit hash\",\"trace.id\":\"unique 'global' id\",\"transaction.id\":\"unique 'local' id\"}\n- : unit = ()\n```\n\nMaybe we're working with URLs - we can log that too!\n```ocaml\n# let uri = Uri.of_string \"https://me:secret@example.com:9090/path?to=success#downhere\";;\nval uri : Uri.t = \u003cabstr\u003e\n# let url_tags = Ecs.add_tags [Ecs.of_uri uri] tags;;\nval url_tags : Logs.Tag.set = \u003cabstr\u003e\n# Logs.info (fun m -\u003e m \"Finished request\" ~tags:url_tags);;\n{\"@timestamp\":\"2052-02-05T20:58:14.386Z\",\"ecs.version\":\"1.5.0\",\"log.level\":\"info\",\"log.logger\":\"application\",\"message\":\"Finished request\",\"url.domain\":\"example.com\",\"url.fragment\":\"downhere\",\"url.full\":\"https://me@example.com:9090/path?to=success#downhere\",\"url.path\":\"/path\",\"url.query\":\"to=success\",\"url.scheme\":\"https\",\"url.username\":\"me\"}\n- : unit = ()\n```\nLook, no passwords!\n\nFile information can be relevant.\n```ocaml\n# let file_tags = Ecs.add_tags [Ecs.file [Hash (Md5 \"INVALID MD5\"); (Size 8192)]] tags;;\nval file_tags : Logs.Tag.set = \u003cabstr\u003e\n# Logs.info (fun m -\u003e m \"Saved file\" ~tags:file_tags);;\n{\"@timestamp\":\"2052-02-05T20:58:14.386Z\",\"ecs.version\":\"1.5.0\",\"file.hash.md5\":\"INVALID MD5\",\"file.size\":8192,\"log.level\":\"info\",\"log.logger\":\"application\",\"message\":\"Saved file\"}\n- : unit = ()\n```\n\nCallsite information is useful but will need a ppx to be less verbose.\n```ocaml\n# let log_tags = Ecs.add_tags [Ecs.log [Origin_file \"README.md\"]] tags;;\nval log_tags : Logs.Tag.set = \u003cabstr\u003e\n# Logs.warn (fun m -\u003e m \"Made it this far\" ~tags:log_tags);;\n{\"@timestamp\":\"2052-02-05T20:58:14.386Z\",\"ecs.version\":\"1.5.0\",\"log.level\":\"warning\",\"log.logger\":\"application\",\"log.origin.file\":\"README.md\",\"message\":\"Made it this far\"}\n- : unit = ()\n```\n\n[ECS]: https://www.elastic.co/guide/en/ecs/current/ecs-reference.html\n[Cmdliner]: http://opam.ocaml.org/packages/cmdliner/\n[Logs]: http://opam.ocaml.org/packages/logs/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhcarty%2Fezlogs-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhcarty%2Fezlogs-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhcarty%2Fezlogs-cli/lists"}