{"id":18141415,"url":"https://github.com/skjolber/json-log-domain","last_synced_at":"2025-04-22T13:14:36.738Z","repository":{"id":22504865,"uuid":"96545701","full_name":"skjolber/json-log-domain","owner":"skjolber","description":"Library supporting JSON-logging with Logback and Stackdriver","archived":false,"fork":false,"pushed_at":"2024-12-29T06:50:34.000Z","size":878,"stargazers_count":6,"open_issues_count":223,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-13T01:41:13.375Z","etag":null,"topics":["gradle","json-logging","logback","logstash","maven","productivity","slf4j","swagger","yaml-format"],"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/skjolber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support/logback-jax-rs/.springBeans","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-07-07T14:19:14.000Z","updated_at":"2021-08-11T08:47:09.000Z","dependencies_parsed_at":"2023-11-14T16:44:28.914Z","dependency_job_id":"e8026421-d9d5-459a-aef4-675f6c915d95","html_url":"https://github.com/skjolber/json-log-domain","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skjolber%2Fjson-log-domain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skjolber%2Fjson-log-domain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skjolber%2Fjson-log-domain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skjolber%2Fjson-log-domain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skjolber","download_url":"https://codeload.github.com/skjolber/json-log-domain/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246201153,"owners_count":20739707,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["gradle","json-logging","logback","logstash","maven","productivity","slf4j","swagger","yaml-format"],"created_at":"2024-11-01T17:06:50.962Z","updated_at":"2025-03-31T02:31:44.512Z","avatar_url":"https://github.com/skjolber.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/skjolber/json-log-domain.svg?branch=master)](https://travis-ci.org/skjolber/json-log-domain)\n\n# json-log-domain\nLibrary supporting JSON-logging. Currently working with [Logback] and [logstash-logback-encoder] and native [Google Stackdriver].\n\nUsers will benefit from\n\n * JSON-logging with domain-specific subtrees\n * Simple YAML-based definition format\n * User-friendly helper-classes generated via [Maven] or [Gradle] plugin\n * Markdown documentation generator\n * Elasticsearch configuration generator\n * JAX-RS log-annotation for [automatic MDC population]\n\nMultiple domains can be combined in the same log statement.\n\nBugs, feature suggestions and help requests can be filed with the [issue-tracker].\n\n## License\n[Apache 2.0]\n\n# Obtain\nThe project is based on [Maven] and is available from central Maven repository. See further down for dependencies.\n\n# Usage\nUsing `static` imports, log expressions can be simplified to (usually) a single line.\n\nThe generated sources allow for writing statements like\n\n```java\nlogger.info(system(\"fedora\").tags(LINUX), \"Hello world\");\n```\n\nfor `SLF4J`, or\n\n```java\nLogEntry entry = DomainLogEntry.newBuilder(system(\"fedora\").tags(LINUX).message(\"Hello world\"))\n    .setSeverity(Severity.INFO)\n    .setLogName(logName)\n    .setResource(MonitoredResource.newBuilder(\"global\").build())\n    .build();\n```\nfor `Stackdriver`. Resulting in\n\n```json\n{\n  \"message\": \"Hello world\",\n  \"system\": \"fedora\",\n  \"tags\": [\"linux\"]\n}\n```\n\n#### Multiple domains\nCombine multiple domains in a single log statement via `and(..)`:\n\n```java\nlogger.info(name(\"java\").version(1.7).tags(JIT) // programming language\n        .and(host(\"127.0.0.1\").port(8080)) // network\n        .and(system(\"Fedora\").tags(LINUX)), // global\n        \"Hello world\"); \n```\n\nfor `SLF4J` or\n\n```java\nLogEntry entry = DomainLogEntry.newBuilder(\n            name(\"java\").version(1.7).tags(JIT)  // programming language\n            .and(host(\"127.0.0.1\").port(8080)) // network\n            .and(system(\"Fedora\").tags(LINUX).message(\"Hello world\")) // global\n        .setSeverity(Severity.INFO)\n        .setLogName(logName)\n        .setResource(MonitoredResource.newBuilder(\"global\").build())\n        .build();\n```\nfor `Stackdriver`. This outputs domain-specific subtrees:\n\n```json\n{\n  \"message\": \"Hello world\",\n  \"language\": {\n    \"name\": \"java\",\n    \"version\": 1.7,\n    \"tags\": [\"JIT\"]\n  },\n  \"network\": {\n    \"port\": 8080,\n    \"host\": \"127.0.0.1\"\n  },\n  \"system\": \"fedora\",\n  \"tags\": [\"linux\"]\n}\n```\n\nwhere the `global` fields are at the root of the message. \n\n## MDC-style logging\nCreate `AutoClosable` scopes using\n\n```java\ntry (AutoCloseable a =  mdc(host(\"localhost\").port(8080))) { // network\n    logger.info().name(\"java\").version(1.7).tags(JIT)  // programming language\n        .and(system(\"Fedora\").tags(LINUX)) // global\n        .message(\"Hello world\");\n}\n```\n\nor the equivalent using try-finally; \n\n```java\nCloseable mdc = mdc(host(\"localhost\").port(8080); // network\ntry {\n    ...\n} finally {\n    mdc.close();\n}\n```\n\nUnlike the built-in SLF4J MDC, the JSON MDC works like a stack. For Logback, see [Logback support] artifact for configuration.\n\n# YAML definition format\nThe relevant fields and tags are defined in a YAML file, from which Java, Markdown and Elastic sources are generated. \n\n![alt text][intro1.png]\n\nExample definition:\n\n```yaml\nversion: '1.0'\nname: Global\npackage: com.example.global\ndescription: Global values\nkeys:\n  - system:\n      name: operating system name\n      type: string\n      description: The system name\n      example: Ubuntu, Windows 10 or Fedora\n  - memory:\n      name: physical memory\n      type: integer\n      format: int32\n      description: Physical memory in megabytes\n      example: 1024, 2048, 16384\ntags:\n - linux: Linux operating system\n - mac: Apple operating system\n - windows: Microsoft windows operating system\n```\n\nThe definition format consists of the fields\n\n  * `version` - file version\n  * `name` - domain name (will prefix generated java sources)\n  * `package` - package of generated sources\n  * `qualifier` - name of domain subtree in logged JSON output (optional) \n  * `description` - textual description of domain\n  * `keys` - list of key-value definitions (see below). \n  * `tags` - list of tag definitions (see below)\n\nIn the above JSON example output, the optional `qualifier` corresponds to `network` and `language` while `keys` include `system`, `port`, `host`, `version`.\n\n### Keys\nEach key is defined by:\n\n * `name` - name of field (Operting System etc)\n * `type` - datatype (string, number, integer etc)\n * `format` - datatype subformat (int32, int64 etc)\n * `description` - textual description of key\n * `example` - example of legal value\n\nThe list item itself is the key in the logged key-value. The type/format datatype definition is borrowed from [Swagger Code Generator]. The intention is that log statements and REST services use the exact same definition for the same data type. Furthermore, framework-level interceptors should be able to pick up interesting fields in JSON objects and/or paths and automatically add those as context to a service invocation, saving the developer valuable time.\n\n### Tags\nEach tag is defined by:\n\n - `name` - a valid Java Enum name\n - `description` - textual description of the tag\n\n# Generating useful outputs\nFiles in the above YAML format can be used to generate Java helper classes, Elastic message configuration and/or Markdown documents.\n\n## Maven plugin\nYAML-files are converted to helper classes using `log-domain-maven-plugin`.\n\n```xml\n\u003cplugin\u003e\n    \u003cgroupId\u003ecom.github.skjolber.log-domain\u003c/groupId\u003e\n    \u003cartifactId\u003elog-domain-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.3\u003c/version\u003e\n    \u003cexecutions\u003e\n        \u003cexecution\u003e\n            \u003cid\u003egenerate\u003c/id\u003e\n            \u003cgoals\u003e\n                \u003cgoal\u003egenerate\u003c/goal\u003e\n            \u003c/goals\u003e\n        \u003c/execution\u003e\n    \u003c/executions\u003e\n    \u003cconfiguration\u003e\n        \u003coutputDirectory\u003e${project.build.directory}/generated-sources/domain-log-codegen\u003c/outputDirectory\u003e\n        \u003ctypes\u003e\n            \u003cmarkdown\u003etrue\u003c/markdown\u003e\n            \u003cjava\u003e\n                \u003clogback\u003etrue\u003c/logback\u003e\n                \u003c!-- OR --\u003e\n                \u003cstackDriver\u003etrue\u003c/stackDriver\u003e\n            \u003c/java\u003e\n        \u003c/types\u003e    \n        \u003cdomains\u003e\n            \u003cdomain\u003e\n                \u003cpath\u003e${basedir}/src/main/resources/yaml/network.yaml\u003c/path\u003elogger\n            \u003c/domain\u003e\n        \u003c/domains\u003e\n    \u003c/configuration\u003e\n\u003c/plugin\u003e\n```\n\n## Gradle plugin\nAdd [Gradle plugin] using\n\n```groovy\nplugins {\n  id \"com.github.skjolber.json-log-domain\" version \"1.0.3\"\n}\n```\n\nand configure a `jsonLogDomain` task\n\n```groovy\njsonLogDomain { \n\tdefinitions = files('src/main/resources/network.yaml')\n\t\n\tlogback {\n\t}\n}\n\nsourceSets {\n    main.java.srcDirs += [jsonLogDomain.logback.outputDirectory]\n}\n```\nwith the addition of `markdown`, `elastic` and `stackDriver` configurations for additional generation.\n\n## Multi-domain\nIn a multi-domain setup, the recommended approach is to generate per-domain artifacts, so that each project only generates helper classes for its own application-specific YAML file and accesses the helper classes for the other domains via a Gradle/Maven dependency.\n\n## Support-library\nA few common classes are not part of the generated sources:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.skjolber.log-domain\u003c/groupId\u003e\n    \u003cartifactId\u003elog-domain-support-logback\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.3\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nor\n\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.skjolber.log-domain\u003c/groupId\u003e\n    \u003cartifactId\u003elog-domain-support-stackdriver\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.3\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Markdown documentation\nA [markdown file] can also be generated for online documentation. \n\n## Elasticsearch configuration\nElasticsearch properties can be generated. One or more of these files can be combined into an application-specific message field mapping, typically at deploy time. See [Elastic example].\n\n# Testing\nLogging is an essential part of any application, verify that logging is performed during unit testing using the [test] libraries.\n\n# Alternatives\nIf you do not like this prosject, maybe you'll like\n\n  * [godaddy-logger]\n  * [slf4jtesting]\n  * [slf4j-json-logger]\n  * [logback-more-appenders]\n\n# See also\n\n  * [Logbook] - configurable request/response-logging\n\n# History\n\n - [1.0.3]: Stackdriver and Gradle support, minor improvements.\n - 1.0.2: JAX-RS helper library, various improvements.\n - 1.0.1: Added MDC support, various improvements.\n - 1.0.0: Initial version\n\n[Apache 2.0]:\t\t\t\t\thttp://www.apache.org/licenses/LICENSE-2.0.html\n[issue-tracker]:\t\t\t\thttps://github.com/skjolber/log-domain/issues\n[Maven]:\t\t\t\t\t\thttp://maven.apache.org/\n[1.0.3]:\t\t\t\t\t\thttps://github.com/skjolber/json-log-domain/releases\n[Logback]:\t\t\t\t\t\thttps://logback.qos.ch/\n[logstash-logback-encoder]:\t\thttps://github.com/logstash/logstash-logback-encoder\n[Swagger Code Generator]:\t\thttps://github.com/swagger-api/swagger-codegen\n[JUnit Rule]:\t\t\t\t\thttps://github.com/junit-team/junit4/wiki/rules\n[markdown file]:\t\t\t\thttps://gist.github.com/skjolber/b79b5c7e4ae40d50305d8d1c9b0c1f71\n[JsonProvider]:\t\t\t\t\thttps://github.com/logstash/logstash-logback-encoder#providers-for-loggingevents\n[pretty-printer]:\t\t\t\ttest/logback/src/main/java/com/github/skjolber/log/domain/test/util/PrettyPrintingDecorator.java\n[Elastic example]: \t\t\t\texamples/elastic-example\n[automatic MDC population]:\t\texamples/jax-rs-example\n[intro1.png]: \t\t\t\t\thttps://raw.githubusercontent.com/skjolber/json-log-domain/master/docs/images/intro1.png \"YAML to multiple formats\"\n[godaddy-logger]:\t\t\t\thttps://github.com/godaddy/godaddy-logger\n[slf4jtesting]:\t\t\t\t\thttps://github.com/portingle/slf4jtesting\n[slf4j-json-logger]:\t\t\thttps://github.com/savoirtech/slf4j-json-logger\n[Google Stackdriver]:\t\t\thttps://cloud.google.com/stackdriver\n[logback-more-appenders]:\t\thttps://github.com/sndyuk/logback-more-appenders\n[Logback support]:\t\t\t\tsupport/logback\n[test]:                         test\n[Gradle]:\t\t\t\t\t\tgradle-plugin\n[logbook]:\t\t\t\t\t\thttps://github.com/zalando/logbook\n[Gradle plugin]:\t\t\t\thttps://plugins.gradle.org/plugin/com.github.skjolber.json-log-domain","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskjolber%2Fjson-log-domain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskjolber%2Fjson-log-domain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskjolber%2Fjson-log-domain/lists"}