{"id":36622409,"url":"https://github.com/soabase/structured-logging","last_synced_at":"2026-01-12T09:26:45.385Z","repository":{"id":57736238,"uuid":"171317253","full_name":"soabase/structured-logging","owner":"soabase","description":"Structured Logging for Java","archived":false,"fork":false,"pushed_at":"2019-03-04T18:50:34.000Z","size":261,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-03T23:27:06.828Z","etag":null,"topics":["elasticsearch","java","logging","logstash","splunk","structured-logging"],"latest_commit_sha":null,"homepage":"","language":"Java","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/soabase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-18T16:24:48.000Z","updated_at":"2023-10-04T00:19:32.000Z","dependencies_parsed_at":"2022-08-23T22:40:53.476Z","dependency_job_id":null,"html_url":"https://github.com/soabase/structured-logging","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/soabase/structured-logging","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soabase%2Fstructured-logging","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soabase%2Fstructured-logging/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soabase%2Fstructured-logging/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soabase%2Fstructured-logging/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soabase","download_url":"https://codeload.github.com/soabase/structured-logging/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soabase%2Fstructured-logging/sbom","scorecard":{"id":835323,"data":{"date":"2025-08-11","repo":{"name":"github.com/soabase/structured-logging","commit":"25ebe870df6806af577059107f2edd58437c4437"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":1.7,"checks":[{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":0,"reason":"55 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-h46c-h94j-95f3","Warn: Project is vulnerable to: GHSA-wf8f-6423-gfxg","Warn: Project is vulnerable to: GHSA-27xj-rqx5-2255","Warn: Project is vulnerable to: GHSA-288c-cq4h-88gq","Warn: Project is vulnerable to: GHSA-4w82-r329-3q67","Warn: Project is vulnerable to: GHSA-57j2-w4cx-62h2","Warn: Project is vulnerable to: GHSA-58pp-9c76-5625","Warn: Project is vulnerable to: GHSA-5949-rw7g-wx7w","Warn: Project is vulnerable to: GHSA-5p34-5m6p-p58g","Warn: Project is vulnerable to: GHSA-5r5r-6hpj-8gg9","Warn: Project is vulnerable to: GHSA-5ww9-j83m-q7qx","Warn: Project is vulnerable to: GHSA-6fpp-rgj9-8rwc","Warn: Project is vulnerable to: GHSA-758m-v56v-grj4","Warn: Project is vulnerable to: GHSA-85cw-hj65-qqv9","Warn: Project is vulnerable to: GHSA-89qr-369f-5m5x","Warn: Project is vulnerable to: GHSA-8c4j-34r4-xr8g","Warn: Project is vulnerable to: GHSA-8w26-6f25-cm9x","Warn: Project is vulnerable to: GHSA-95cm-88f5-f2c7","Warn: Project is vulnerable to: GHSA-9gph-22xh-8x98","Warn: Project is vulnerable to: GHSA-9m6f-7xcq-8vf8","Warn: Project is vulnerable to: GHSA-9vvp-fxw6-jcxr","Warn: Project is vulnerable to: GHSA-c265-37vj-cwcc","Warn: Project is vulnerable to: GHSA-c2q3-4qrh-fm48","Warn: Project is vulnerable to: GHSA-cf6r-3wgc-h863","Warn: Project is vulnerable to: GHSA-cmfg-87vq-g5g4","Warn: Project is vulnerable to: GHSA-cvm9-fjm9-3572","Warn: Project is vulnerable to: GHSA-f3j5-rmmp-3fc5","Warn: Project is vulnerable to: GHSA-f9xh-2qgp-cq57","Warn: Project is vulnerable to: GHSA-fmmc-742q-jg75","Warn: Project is vulnerable to: GHSA-fqwf-pjwf-7vqv","Warn: Project is vulnerable to: GHSA-gjmw-vf9h-g25v","Warn: Project is vulnerable to: GHSA-gwp4-hfv6-p7hw","Warn: Project is vulnerable to: GHSA-gww7-p5w4-wrfv","Warn: Project is vulnerable to: GHSA-h3cw-g4mq-c5x2","Warn: Project is vulnerable to: GHSA-h4rc-386g-6m85","Warn: Project is vulnerable to: GHSA-h822-r4r5-v8jg","Warn: Project is vulnerable to: GHSA-j823-4qch-3rgm","Warn: Project is vulnerable to: GHSA-jjjh-jjxp-wpff","Warn: Project is vulnerable to: GHSA-m6x4-97wx-4q27","Warn: Project is vulnerable to: GHSA-mc6h-4qgp-37qh","Warn: Project is vulnerable to: GHSA-mph4-vhrx-mv67","Warn: Project is vulnerable to: GHSA-mx7p-6679-8g3q","Warn: Project is vulnerable to: GHSA-p43x-xfjf-5jhr","Warn: Project is vulnerable to: GHSA-q93h-jc49-78gg","Warn: Project is vulnerable to: GHSA-qjw2-hr98-qgfh","Warn: Project is vulnerable to: GHSA-qmqc-x3r4-6v39","Warn: Project is vulnerable to: GHSA-r3gr-cxrf-hg25","Warn: Project is vulnerable to: GHSA-r695-7vr9-jgc2","Warn: Project is vulnerable to: GHSA-rf6r-2c4q-2vwg","Warn: Project is vulnerable to: GHSA-rgv9-q543-rqg4","Warn: Project is vulnerable to: GHSA-rpr3-cw39-3pxh","Warn: Project is vulnerable to: GHSA-v3xw-c963-f5hc","Warn: Project is vulnerable to: GHSA-v585-23hc-c647","Warn: Project is vulnerable to: GHSA-vfqx-33qm-g869","Warn: Project is vulnerable to: GHSA-wh8g-3j2c-rqj5"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-23T18:51:59.035Z","repository_id":57736238,"created_at":"2025-08-23T18:51:59.036Z","updated_at":"2025-08-23T18:51:59.036Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["elasticsearch","java","logging","logstash","splunk","structured-logging"],"created_at":"2026-01-12T09:26:44.558Z","updated_at":"2026-01-12T09:26:45.378Z","avatar_url":"https://github.com/soabase.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://api.travis-ci.org/soabase/structured-logging.svg?branch=master)](https://travis-ci.org/soabase/structured-logging)\n[![Maven Central](https://img.shields.io/maven-central/v/io.soabase.structured-logger/structured-logger-core.svg)](http://search.maven.org/#search%7Cga%7C1%7Cstructured-logger)\n\n# Structured Logging\n\n[Per Thoughtworks](https://www.thoughtworks.com/radar/techniques/structured-logging) we should log in a structured manner...\n\n[Per Splunk](http://dev.splunk.com/view/logging/SP-CAAAFCK): \"Use clear key-value pairs. One of the most powerful features of Splunk software is its ability to extract fields from events when you search, creating structure out of unstructured data.\"\n\n[Per Elasticsearch](https://www.elastic.co/blog/structured-logging-filebeat): \"[Logging] works best when the logs are pre-parsed in a structured object, so you can search and aggregate on individual fields.\" It can already be done in Go or Python so why not Java?\n\nIf you export your logs to a centralized indexer, structuring your logging will make the indexer's job much easier and you will be able to get more and better information out of your logs. Manual structured logging is error prone and requires too much discipline. We can do better.\n\n### With Structured Logging And Preprocessor\n\n```java\n@LoggerSchema({Id.class, Qty.class, Event.class})  // note: the library preprocessor generates the schema\npublic class MyClass {\n    private static final StructuredLogger\u003cMyClassSchema\u003e log = StructuredLoggerFactory.structured(MyClassSchema.class);  // note: the library auto-generates the schema instance class\n\n    private void myOperation() {\n    ...\n    \n        log.info(\"Something happened\", schema -\u003e schema.event(\"creation event\").id(10064).qty(100));\n    }\n}\n```\n\nLogs similar to: `id=\"10064\" event=\"creation event\" qty=\"100\" Something happened`\n\n### With Just Structured Logging\n\n```java\n\npublic interface LogSchema {\n    LogSchema id(String id);\n    \n    LogSchema qty(int qty);\n    \n    LogSchema event(String name);\n}\n\n...\n\nStructuredLogger\u003cLogSchema\u003e log = StructuredLoggerFactory.structured(LogSchema.class);  // note: the library auto-generates the schema instance class\n\n...\n\nprivate void myOperation() {\n    ...\n    \n        log.info(\"Something happened\", schema -\u003e schema.event(\"creation event\").id(10064).qty(100));\n}\n```\n\nLogs similar to: `id=\"10064\" event=\"creation event\" qty=\"100\" Something happened`\n\n### Without Structured Logging\n\n```java\nLogger log = LoggerFactory.getLogger(...);\n\n...\n\nprivate void myOperation(String id, String eventName, int qty) {\n    ...\n    \n        // note mistakes misspellings\n    log.info(\"Something happened where id={} eventnme={}and qty = {}\", id, qty, eventName);\n}\n```\n\n### Create a Registry With All the Logging Schema For Your Project\n\n```java\n@LoggerSchemas({\n        @LoggerSchema(value = {Id.class, Code.class}, schemaName = \"LoggingSchemaIdCode\"),\n        @LoggerSchema(value = {Id.class, Event.class}, schemaName = \"LoggingSchemaIdEvent\"),\n        @LoggerSchema(value = Id.class, schemaName = \"LoggingSchemaId\"),\n        @LoggerSchema(value = {Id.class, CustomSchema.class}, schemaName = \"LoggingSchemaIdCustom\")\n})\npublic class LoggingSchema {\n}\n```\n\n### Make Some Values Required\n\nIf you would like to require certain schema values to not be omitted, annotate them with `@Required`. E.g.\n\n```java\npublic interface MySchema {\n    @Required\n    MySchema auth(String authValue);\n}\n```\n\nThe Structured Logger will throw `MissingSchemaValueException` if no value is set for required values. Note: if you want to only use this in development or pre-production, you can globally disable required value checking by calling `StructuredLoggerFactory.setRequiredValuesEnabled(false)`.\n\n### Change Ordering\n\nBy default, schema values are output in alphabetical order. Add `@SortOrder` annotations to change this. E.g.\n\n```java\npublic interface SchemaWithSort {\n    SchemaWithSort id(String id);\n\n    SchemaWithSort bool(boolean b);\n\n    @SortOrder(1)\n    SchemaWithSort qty(int qty);\n\n    @SortOrder(0)\n    SchemaWithSort zero(int z);\n}\n```\nThis schema will be output ala: `zero=xxx qty=xxx bool=xxx id=xxx`\n\n### Formatting\n\nThe formatting of the log message is customizable. Two formatters are provided, `DefaultLoggingFormatter` and `GelfLoggingFormatter`.\n\n_DefaultLoggingFormatter_\n\nThe DefaultLoggingFormatter formats the log in `field=value` pairs and has several options. Values can be quoted and/or escaped and the log main message can appear at the beginning or the end of the log string.\n\n_GelfLoggingFormatter_\n\nThe GelfLoggingFormatter formats in the [GELF](http://docs.graylog.org/en/2.5/pages/gelf.html) 1.1 JSON format.\n\nYou change the logging formatter used by default by calling `StructuredLoggerFactory.setDefaultLoggingFormatter(...)`. You can also specify a logging formatter when creating structured logger instances.\n\n## Under The Hood\n\n- The schema concrete instance is generated from the interface using Byte Buddy here: [Generator.java](https://github.com/soabase/structured-logging/blob/master/structured-logger-core/src/main/java/io/soabase/structured/logger/generation/Generator.java)\n  - Don't like generators/ByteBuddy? Write your own: [SPI](https://github.com/soabase/structured-logging/tree/master/structured-logger-core/src/main/java/io/soabase/structured/logger/spi)\n- The logging facade forwards directly to SLF4J (or whatever). This is not a new logging library.\n- If writing a little interface schema is too much trouble, there's a preprocessor that will generate one from \"mixins\". See the example here: [TestGenerated.java](https://github.com/soabase/structured-logging/blob/master/structured-logger-generator-test/src/test/java/io/soabase/structured/logger/TestGenerated.java)\n- You can create \"factories\" that generate multiple/all of your logging schema in one place. Example here: [SampleSchemaFactory.java](https://github.com/soabase/structured-logging/blob/master/structured-logger-generator-test/src/test/java/io/soabase/structured/logger/SampleSchemaFactory.java)\n- A set of common \"mixin\" logging schema are included: [Included Schema](https://github.com/soabase/structured-logging/tree/master/structured-logger-core/src/main/java/io/soabase/structured/logger/schemas)\n- Very small (\u003c 50K) library with minimal third party dependencies (only ByteBuddy and SLF4J)\n\n## Performance / Benchmarks\n\nPerformance is nearly identical to raw SLF4J:\n\n```\nOps/s            Min    Avg    Max   \nRaw SLF4J:     301711 305972 310233\nStructured:    273331 293237 313143\n(Results obtained via JMH)\n```\n\n\n## Usage\n\n| Group ID | Artifact ID | Description |\n| -------- | ----------- | ----------- |\n| `io.soabase.structured-logger` | `structured-logger-core` | The main library. You will also need to add SLF4J to your dependency manager |\n| `io.soabase.structured-logger` | `structured-logger-generator` | Annotation processor for building Schema. Make sure your IDE or build tool has annotation processing enabled |\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoabase%2Fstructured-logging","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoabase%2Fstructured-logging","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoabase%2Fstructured-logging/lists"}