{"id":13593282,"url":"https://github.com/logfellow/logstash-logback-encoder","last_synced_at":"2025-12-16T20:00:49.701Z","repository":{"id":7248654,"uuid":"8559429","full_name":"logfellow/logstash-logback-encoder","owner":"logfellow","description":"Logback JSON encoder and appenders","archived":false,"fork":false,"pushed_at":"2025-11-10T00:03:27.000Z","size":3817,"stargazers_count":2511,"open_issues_count":35,"forks_count":415,"subscribers_count":62,"default_branch":"main","last_synced_at":"2025-12-08T19:21:36.579Z","etag":null,"topics":["json","logback","logback-appender","logstash"],"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/logfellow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2013-03-04T16:19:08.000Z","updated_at":"2025-12-05T09:26:18.000Z","dependencies_parsed_at":"2023-02-18T05:31:23.611Z","dependency_job_id":"310343e3-dfa9-4070-b186-a897ffab2bad","html_url":"https://github.com/logfellow/logstash-logback-encoder","commit_stats":{"total_commits":1013,"total_committers":95,"mean_commits":"10.663157894736843","dds":0.7581441263573544,"last_synced_commit":"76f5295f35bc44518af91bfccb07a8ecb142229c"},"previous_names":["logstash/logstash-logback-encoder"],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/logfellow/logstash-logback-encoder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logfellow%2Flogstash-logback-encoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logfellow%2Flogstash-logback-encoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logfellow%2Flogstash-logback-encoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logfellow%2Flogstash-logback-encoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/logfellow","download_url":"https://codeload.github.com/logfellow/logstash-logback-encoder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logfellow%2Flogstash-logback-encoder/sbom","scorecard":{"id":597174,"data":{"date":"2025-08-11","repo":{"name":"github.com/logfellow/logstash-logback-encoder","commit":"c2a913a5220b0b8c3623bdc357d312c3e6681894"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4,"checks":[{"name":"Code-Review","score":1,"reason":"Found 4/26 approved changesets -- score normalized to 1","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":"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":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/build.yml:1","Warn: no topLevel permission defined: .github/workflows/codeql-analysis.yml:1","Warn: no topLevel permission defined: .github/workflows/no-response.yml:1","Info: no jobLevel write permissions found"],"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":"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":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","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":"Binary-Artifacts","score":9,"reason":"binaries present in source code","details":["Warn: binary detected: .mvn/wrapper/maven-wrapper.jar:1"],"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":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Info: Possibly incomplete results: error parsing shell code: not a valid arithmetic operator: ': .github/workflows/steps/setup-gpg.sh:0","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/logfellow/logstash-logback-encoder/build.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/logfellow/logstash-logback-encoder/build.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/logfellow/logstash-logback-encoder/build.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/logfellow/logstash-logback-encoder/build.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/build.yml:50: update your workflow using https://app.stepsecurity.io/secureworkflow/logfellow/logstash-logback-encoder/build.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:63: update your workflow using https://app.stepsecurity.io/secureworkflow/logfellow/logstash-logback-encoder/build.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:68: update your workflow using https://app.stepsecurity.io/secureworkflow/logfellow/logstash-logback-encoder/build.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:84: update your workflow using https://app.stepsecurity.io/secureworkflow/logfellow/logstash-logback-encoder/build.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/logfellow/logstash-logback-encoder/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:28: update your workflow using https://app.stepsecurity.io/secureworkflow/logfellow/logstash-logback-encoder/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/logfellow/logstash-logback-encoder/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/logfellow/logstash-logback-encoder/codeql-analysis.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/no-response.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/logfellow/logstash-logback-encoder/no-response.yml/main?enable=pin","Info:   0 out of  11 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   2 third-party GitHubAction dependencies pinned"],"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":"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":"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":"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":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'main'"],"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":"SAST","score":9,"reason":"SAST tool detected but not run on all commits","details":["Info: SAST configuration detected: CodeQL","Warn: 14 commits out of 17 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"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-20T23:25:43.439Z","repository_id":7248654,"created_at":"2025-08-20T23:25:43.439Z","updated_at":"2025-08-20T23:25:43.439Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27770466,"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","status":"online","status_checked_at":"2025-12-16T02:00:10.477Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["json","logback","logback-appender","logstash"],"created_at":"2024-08-01T16:01:18.723Z","updated_at":"2025-12-16T20:00:49.678Z","avatar_url":"https://github.com/logfellow.png","language":"Java","readme":"\u003e [!IMPORTANT]\n\u003e This document applies to the next version under development.\n\u003e\n\u003e \u0026nbsp; \u0026nbsp; See [here for documentation on the latest released version](https://github.com/logfellow/logstash-logback-encoder/tree/logstash-logback-encoder-9.0).\n\n# Logstash Logback Encoder\n\n[![Build](https://github.com/logfellow/logstash-logback-encoder/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/logfellow/logstash-logback-encoder/actions/workflows/build.yml)\n[![Javadocs](http://www.javadoc.io/badge/net.logstash.logback/logstash-logback-encoder.svg)](http://www.javadoc.io/doc/net.logstash.logback/logstash-logback-encoder)\n[![Maven Central](https://img.shields.io/maven-central/v/net.logstash.logback/logstash-logback-encoder)](https://search.maven.org/artifact/net.logstash.logback/logstash-logback-encoder)\n[![Release Notes](https://img.shields.io/github/v/release/logfellow/logstash-logback-encoder?label=release%20notes)](https://github.com/logfellow/logstash-logback-encoder/releases/latest)\n\nProvides [logback](http://logback.qos.ch/) encoders, layouts, and appenders to log in JSON and [other formats supported by Jackson](#data-format).\n\nSupports both regular _LoggingEvents_ (logged through a `Logger`) and _AccessEvents_ (logged via [logback-access](http://logback.qos.ch/access.html)).\n\nOriginally written to support output in [logstash](https://www.elastic.co/guide/en/logstash/current)'s JSON format, but has evolved into a highly-configurable, general-purpose, structured logging mechanism for JSON and other Jackson dataformats.\nThe structure of the output, and the data it contains, is fully configurable.\n\n#### Contents:\n\n* [Including it in your project](#including-it-in-your-project)\n* [Java Version Requirements](#java-version-requirements)\n* [Usage](#usage)\n\t* [UDP Appenders](#udp-appenders)\n\t* [TCP Appenders](#tcp-appenders)\n\t\t* [Keep-alive](#keep-alive)\n\t\t* [Multiple Destinations](#multiple-destinations)\n\t\t* [Reconnection Delay](#reconnection-delay)\n\t\t* [Connection Timeout](#connection-timeout)\n\t\t* [Write Buffer Size](#write-buffer-size)\n\t\t* [Write Timeout](#write-timeout)\n\t\t* [Initial Send Delay](#initial-send-delay)\n\t\t* [SSL](#ssl)\n\t* [Async Appenders](#async-appenders)\n\t\t* [RingBuffer Size](#ringbuffer-size)\n\t\t* [RingBuffer Full](#ringbuffer-full)\n\t\t* [Graceful Shutdown](#graceful-shutdown)\n\t\t* [Wait Strategy](#wait-strategy)\n\t* [Appender Listeners](#appender-listeners)\n\t* [Encoders / Layouts](#encoders--layouts)\n    * [Threads and ThreadLocals](#threads-and-threadlocals)\n* [LoggingEvent Fields](#loggingevent-fields)\n\t* [Standard Fields](#standard-fields)\n\t* [MDC fields](#mdc-fields)\n\t* [Key Value Pair fields](#key-value-pair-fields)\n\t* [Context fields](#context-fields)\n\t* [Caller Info Fields](#caller-info-fields)\n\t* [Custom Fields](#custom-fields)\n\t\t* [Global Custom Fields](#global-custom-fields)\n\t\t* [Event-specific Custom Fields](#event-specific-custom-fields)\n* [AccessEvent Fields](#accessevent-fields)\n\t* [Standard Fields](#standard-fields-1)\n\t* [Header Fields](#header-fields)\n* [Customizing Jackson](#customizing-jackson)\n\t* [Data Format](#data-format)\n\t* [Customizing TokenStreamFactory, ObjectMapper, and JsonGenerator](#customizing-tokenstreamfactory-objectmapper-and-jsongenerator)\n\t* [Registering Jackson Modules](#registering-jackson-modules)\n\t* [Customizing Character Escapes](#customizing-character-escapes)\n* [Masking](#masking)\n* [Customizing Standard Field Names](#customizing-standard-field-names)\n* [Customizing Version](#customizing-version)\n* [Customizing Timestamp](#customizing-timestamp)\n* [Customizing LoggingEvent Message](#customizing-loggingevent-message)\n* [Customizing AccessEvent Message](#customizing-accessevent-message)\n* [Customizing Logger Name Length](#customizing-logger-name-length)\n* [Customizing Stack Traces](#customizing-stack-traces)\n    * [Omit Common Frames](#omit-common-frames)\n    * [Truncate after Regex](#truncate-after-regex)\n    * [Exclude Frames per Regex](#exclude-frames-per-regex)\n    * [Omit Throwable Messages](#omit-throwable-messages)\n    * [Maximum Depth per Throwable](#maximum-depth-per-throwable)\n    * [Maximum Trace Size (bytes)](#maximum-trace-size-bytes)\n    * [Classname Shortening](#classname-shortening)\n    * [Custom Line Separator](#custom-line-separator)\n    * [Root Cause First](#root-cause-first)\n    * [Conditional Output](#conditional-output)\n    * [Stack Hashes](#stack-hashes)\n    * [Using with PatternLayout](#using-with-patternlayout)\n* [Registering Additional Providers](#registering-additional-providers)\n* [Prefix/Suffix/Separator](#prefixsuffixseparator)\n* [Composite Encoder/Layout](#composite-encoderlayout)\n\t* [Providers common to LoggingEvents and AccessEvents](#providers-common-to-loggingevents-and-accessevents)\n\t* [Providers for LoggingEvents](#providers-for-loggingevents)\n\t* [Providers for AccessEvents](#providers-for-accessevents)\n\t* [Nested JSON Provider](#nested-json-provider)\n\t* [Pattern JSON Provider](#pattern-json-provider)\n\t\t* [LoggingEvent patterns](#loggingevent-patterns)\n\t\t* [AccessEvent patterns](#accessevent-patterns)\n\t* [Custom JSON Provider](#custom-json-provider)\n* [Status Listeners](#status-listeners)\n* [Joran/XML Configuration](#joranxml-configuration)\n\t* [Duration Property](#duration-property)\n\t* [Comma separated list of values](#comma-separated-list-of-values)\n\n\n## Including it in your project\n\nMaven style:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003enet.logstash.logback\u003c/groupId\u003e\n    \u003cartifactId\u003elogstash-logback-encoder\u003c/artifactId\u003e\n    \u003cversion\u003e9.0\u003c/version\u003e\n    \u003c!-- Use runtime scope if the project does not have any compile-time usage of logstash-logback-encoder,\n         such as usage of StructuredArguments/Markers or implementations such as\n         JsonProvider, AppenderListener, JsonFactoryDecorator, JsonGeneratorDecorator, etc\n    \u003cscope\u003eruntime\u003c/scope\u003e\n    --\u003e\n\u003c/dependency\u003e\n\u003c!-- Your project must also directly depend on either logback-classic or logback-access. For example: --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003ech.qos.logback\u003c/groupId\u003e\n    \u003cartifactId\u003elogback-classic\u003c/artifactId\u003e\n    \u003cversion\u003e1.5.20\u003c/version\u003e\n    \u003c!-- Use runtime scope if the project does not have any compile-time usage of logback,\n         such as implementations of Appender, Encoder, Layout, TurboFilter, etc\n    \u003cscope\u003eruntime\u003c/scope\u003e\n    --\u003e\n\u003c/dependency\u003e\n```\n\nIf you get `ClassNotFoundException`/`NoClassDefFoundError`/`NoSuchMethodError` at runtime,\nthen ensure the required dependencies (and appropriate versions) as specified in the pom file\nfrom the maven repository exist on the runtime classpath.\nSpecifically, the following need to be available on the runtime classpath:\n\n* jackson-databind / jackson-core / jackson-annotations \u003e= 3.0.0\n* logback-core \u003e= 1.5.0\n* logback-classic \u003e= 1.5.0 (required for logging _LoggingEvents_)\n* logback-access \u003e= 2.0.0 (required for logging _AccessEvents_)\n* slf4j-api (usually comes as a transitive dependency of logback-classic)\n* java-uuid-generator (required if the `uuid` provider is used)\n\nOlder versions than the ones specified in the pom file _might_ work, but the versions in the pom file are what testing has been performed against.\nSupport for logback versions prior to 1.3.0 was removed in logstash-logback-encoder 7.4.\nSupport for jackson versions prior to 3.0.0 was removed in logstash-logback-encoder 9.0.\n\nIf you are using logstash-logback-encoder in a project (such as spring-boot) that also declares dependencies on any of the above libraries, you might need to tell maven explicitly which versions to use to avoid conflicts.\nYou can do so using maven's [dependencyManagement](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Dependency_Management) feature.\nFor example, to ensure that maven doesn't pick different versions of logback-core, logback-classic, and logback-access, add this to your project's pom.xml\n\n```xml\n\u003cproperties\u003e\n    \u003clogback-classic.version\u003e1.5.20\u003c/logback-classic.version\u003e\n    \u003clogback-access.version\u003e2.0.6\u003c/logback-access.version\u003e\n\u003c/properties\u003e\n\u003cdependencyManagement\u003e\n    \u003cdependencies\u003e\n        \u003cdependency\u003e\n            \u003cgroupId\u003ech.qos.logback\u003c/groupId\u003e\n            \u003cartifactId\u003elogback-core\u003c/artifactId\u003e\n            \u003cversion\u003e${logback-classic.version}\u003c/version\u003e\n        \u003c/dependency\u003e\n        \u003cdependency\u003e\n            \u003cgroupId\u003ech.qos.logback\u003c/groupId\u003e\n            \u003cartifactId\u003elogback-classic\u003c/artifactId\u003e\n            \u003cversion\u003e${logback-classic.version}\u003c/version\u003e\n        \u003c/dependency\u003e\n        \u003cdependency\u003e\n            \u003cgroupId\u003ech.qos.logback.access\u003c/groupId\u003e\n            \u003cartifactId\u003elogback-access-common\u003c/artifactId\u003e\n            \u003cversion\u003e${logback-access.version}\u003c/version\u003e\n        \u003c/dependency\u003e\n    \u003c/dependencies\u003e\n\u003c/dependencyManagement\u003e\n```\n\n## Java Version Requirements\n\n| logstash-logback-encoder | Minimum Java Version supported |\n|--------------------------|--------------------------------|\n| 9.x                      | 17                             |\n| 8.x                      | 11                             |\n| 7.x                      | 8                              |\n| 6.x                      | 8                              |\n| 5.x                      | 7                              |\n| \u0026lt;= 4.x                | 6                              |\n\n\n## Usage\n\nTo log using JSON format, you must configure logback to use either:\n\n* an appender provided by the logstash-logback-encoder library, OR\n* an appender provided by logback (or another library) with an encoder or layout provided by the logstash-logback-encoder library\n\nThe appenders, encoders, and layouts provided by the logstash-logback-encoder library are as follows:\n\n| Format        | Protocol   | Function | LoggingEvent                                                                                                                 | AccessEvent                                                                                                                |\n|---------------|------------|----------|------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|\n| Logstash JSON | Syslog/UDP | Appender | [`LogstashUdpSocketAppender`](/src/main/java/net/logstash/logback/appender/LogstashUdpSocketAppender.java)                   | [`LogstashAccessUdpSocketAppender`](/src/main/java/net/logstash/logback/appender/LogstashAccessUdpSocketAppender.java)     |\n| Logstash JSON | TCP        | Appender | [`LogstashTcpSocketAppender`](/src/main/java/net/logstash/logback/appender/LogstashTcpSocketAppender.java)                   | [`LogstashAccessTcpSocketAppender`](/src/main/java/net/logstash/logback/appender/LogstashAccessTcpSocketAppender.java)     |\n| any           | any        | Appender | [`LoggingEventAsyncDisruptorAppender`](/src/main/java/net/logstash/logback/appender/LoggingEventAsyncDisruptorAppender.java) | [`AccessEventAsyncDisruptorAppender`](/src/main/java/net/logstash/logback/appender/AccessEventAsyncDisruptorAppender.java) |\n| Logstash JSON | any        | Encoder  | [`LogstashEncoder`](/src/main/java/net/logstash/logback/encoder/LogstashEncoder.java)                                        | [`LogstashAccessEncoder`](/src/main/java/net/logstash/logback/encoder/LogstashAccessEncoder.java)                          |\n| Logstash JSON | any        | Layout   | [`LogstashLayout`](/src/main/java/net/logstash/logback/layout/LogstashLayout.java)                                           | [`LogstashAccessLayout`](/src/main/java/net/logstash/logback/layout/LogstashAccessLayout.java)                             |\n| General JSON  | any        | Encoder  | [`LoggingEventCompositeJsonEncoder`](/src/main/java/net/logstash/logback/encoder/LoggingEventCompositeJsonEncoder.java)      | [`AccessEventCompositeJsonEncoder`](/src/main/java/net/logstash/logback/encoder/AccessEventCompositeJsonEncoder.java)      |\n| General JSON  | any        | Layout   | [`LoggingEventCompositeJsonLayout`](/src/main/java/net/logstash/logback/layout/LoggingEventCompositeJsonLayout.java)         | [`AccessEventCompositeJsonLayout`](/src/main/java/net/logstash/logback/encoder/AccessEventCompositeJsonLayout.java)        |\n\nThese encoders/layouts can generally be used by any logback appender (such as `RollingFileAppender`).\n\nThe general _composite_ JSON encoders/layouts can be used to\noutput any JSON format/data by configuring them with various JSON _providers_.\nThe Logstash encoders/layouts are really just extensions of the general\ncomposite JSON encoders/layouts with a pre-defined set of providers.\n\nThe logstash encoders/layouts are easier to configure if you want to use the standard logstash version 1 output format.\nUse the [composite encoders/layouts](#composite-encoderlayout) if you want to heavily customize the output,\nor if you need to use logstash version 0 output.\n\nThe `*AsyncDisruptorAppender` appenders are similar to logback's `AsyncAppender`,\nexcept that a [LMAX Disruptor RingBuffer](https://lmax-exchange.github.io/disruptor/)\nis used as the queuing mechanism, as opposed to a `BlockingQueue`.\nThese async appenders can delegate to any other underlying logback appender.\n\n\n\n### UDP Appenders\n\nTo output JSON for LoggingEvents to a syslog/UDP channel,\nuse the `LogstashUdpSocketAppender` with a `LogstashLayout` or `LoggingEventCompositeJsonLayout`\nin your `logback.xml`, like this:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cconfiguration\u003e\n    \u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashUdpSocketAppender\"\u003e\n        \u003chost\u003eMyAwesomeSyslogServer\u003c/host\u003e\n        \u003c!-- port is optional (default value shown) --\u003e\n        \u003cport\u003e514\u003c/port\u003e\n        \u003c!-- layout is required --\u003e\n        \u003clayout class=\"net.logstash.logback.layout.LogstashLayout\"/\u003e\n    \u003c/appender\u003e\n    \n    \u003croot level=\"all\"\u003e\n        \u003cappender-ref ref=\"stash\" /\u003e\n    \u003c/root\u003e\n\u003c/configuration\u003e\n```\nYou can further customize the JSON output by customizing the layout as described in later sections.\n\nFor example, to configure [global custom fields](#global-custom-fields), you can specify\n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashUdpSocketAppender\"\u003e\n    \u003chost\u003eMyAwesomeSyslogServer\u003c/host\u003e\n    \u003c!-- port is optional (default value shown) --\u003e\n    \u003cport\u003e514\u003c/port\u003e\n    \u003clayout class=\"net.logstash.logback.layout.LogstashLayout\"\u003e\n        \u003ccustomFields\u003e{\"appname\":\"myWebservice\"}\u003c/customFields\u003e\n    \u003c/layout\u003e\n\u003c/appender\u003e\n```\n\nTo output JSON for AccessEvents over UDP, use a `LogstashAccessUdpSocketAppender`\nwith a `LogstashAccessLayout` or `AccessEventCompositeJsonLayout`\nin your `logback-access.xml`, like this:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cconfiguration\u003e\n    \u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashAccessUdpSocketAppender\"\u003e\n        \u003chost\u003eMyAwesomeSyslogServer\u003c/host\u003e\n        \u003c!-- port is optional (default value shown) --\u003e\n        \u003cport\u003e514\u003c/port\u003e\n\n        \u003clayout class=\"net.logstash.logback.layout.LogstashAccessLayout\"\u003e\n            \u003ccustomFields\u003e{\"appname\":\"myWebservice\"}\u003c/customFields\u003e\n        \u003c/layout\u003e\n    \u003c/appender\u003e\n\n    \u003cappender-ref ref=\"stash\" /\u003e\n\u003c/configuration\u003e\n```\n\n\nTo receive syslog/UDP input in logstash, configure a [`syslog`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-syslog.html) or [`udp`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-udp.html) input with the [`json`](https://www.elastic.co/guide/en/logstash/current/plugins-codecs-json.html) codec in logstash's configuration like this:\n```\ninput {\n    syslog {\n        codec =\u003e \"json\"\n    }\n}\n```\n\n\n### TCP Appenders\n\nTo output JSON for LoggingEvents over TCP, use a `LogstashTcpSocketAppender`\nwith a `LogstashEncoder` or `LoggingEventCompositeJsonEncoder`\nin your `logback.xml`, like this:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cconfiguration\u003e\n    \u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u003e\n        \u003cdestination\u003e127.0.0.1:4560\u003c/destination\u003e\n\n        \u003c!-- encoder is required --\u003e\n        \u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\" /\u003e\n    \u003c/appender\u003e\n\n    \u003croot level=\"DEBUG\"\u003e\n        \u003cappender-ref ref=\"stash\" /\u003e\n    \u003c/root\u003e\n\u003c/configuration\u003e\n```\n\n\nTo output JSON for AccessEvents over TCP, use a `LogstashAccessTcpSocketAppender`\nwith a `LogstashAccessEncoder` or `AccessEventCompositeJsonEncoder`\nin your `logback-access.xml`, like this:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cconfiguration\u003e\n    \u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashAccessTcpSocketAppender\"\u003e\n        \u003cdestination\u003e127.0.0.1:4560\u003c/destination\u003e\n\n        \u003c!-- encoder is required --\u003e\n        \u003cencoder class=\"net.logstash.logback.encoder.LogstashAccessEncoder\" /\u003e\n    \u003c/appender\u003e\n\n    \u003cappender-ref ref=\"stash\" /\u003e\n\u003c/configuration\u003e\n```\n\nThe TCP appenders use an encoder, rather than a layout as the [UDP appenders](#udp-appenders) . \nYou can use a `Logstash*Encoder`, `*EventCompositeJsonEncoder`, or any other logback encoder.\nAll the output formatting options are configured at the encoder level.\n\nInternally, the TCP appenders are asynchronous (using the [LMAX Disruptor RingBuffer](https://lmax-exchange.github.io/disruptor/)).\nAll the encoding and TCP communication is delegated to a single writer thread.\nThere is no need to wrap the TCP appenders with another asynchronous appender\n(such as `AsyncAppender` or `LoggingEventAsyncDisruptorAppender`).\n\nAll the configuration parameters (except for sub-appender) of the [async appenders](#async-appenders) are valid for TCP appenders. For example, `waitStrategyType` and `ringBufferSize`.\n\nBy default, the TCP appenders will never block the logging thread - if the RingBuffer is full (e.g. due to slow network, etc), then events will be dropped. If desired, the appender can also be configured to block and wait for free space, see [RingBuffer Full](#ringbuffer-full) for more information.\n\nThe TCP appenders will automatically reconnect if the connection breaks. Multiple destinations can be configured to increase availability and reduce message lost. See [Multiple Destinations](#multiple-destinations) for more information.\n\nTo receive TCP input in logstash, configure a [`tcp`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-tcp.html) input with the [`json_lines`](https://www.elastic.co/guide/en/logstash/current/plugins-codecs-json_lines.html) codec in logstash's configuration like this:\n\n```\ninput {\n    tcp {\n        port =\u003e 4560\n            codec =\u003e json_lines\n    }\n}\n```\n\nTo guarantee that logged messages have had a chance to be processed by the TCP appender, you'll need to [cleanly shut down logback](http://logback.qos.ch/manual/configuration.html#stopContext) when your application exits.\n\n\n#### Keep-Alive\n\nIf events occur infrequently, and the connection breaks consistently due to a server-side idle timeout,\nthen you can enable keep alive functionality by configuring a `keepAliveDuration` like this:\n\n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u003e\n    ...\n    \u003ckeepAliveDuration\u003e5 minutes\u003c/keepAliveDuration\u003e\n\u003c/appender\u003e\n```\n\nThis setting accepts a Logback Duration value - see the section dedicated to [Duration Property](#duration-property) for more information about the valid values.\n\nWhen the `keepAliveDuration` is set, then a keep alive message will be sent if an event has not occurred for the length of the duration.\nThe keep alive message defaults to unix line ending (`\\n`), but can be changed by setting the `keepAliveMessage` property to the desired value. The following values have special meaning:\n\n- `\u003cempty string\u003e`: no keep alive\n- `SYSTEM`: system's line separator\n- `UNIX`: unix line ending (`\\n`)\n- `WINDOWS`: windows line ending (`\\r\\n`)\n\nAny other value will be used as-is.\n\nThe keep alive message is encoded in `UTF-8` by default. This can be changed by setting the `keepAliveCharset` property to the name of the desired charset.\n\n\n#### Multiple Destinations\n\nThe TCP appenders can be configured to try to connect to one of several destinations like this:\n\n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u003e\n    \u003cdestination\u003edestination1.domain.com:4560\u003c/destination\u003e\n    \u003cdestination\u003edestination2.domain.com:4560\u003c/destination\u003e\n    \u003cdestination\u003edestination3.domain.com:4560\u003c/destination\u003e\n\n    ...\n\u003c/appender\u003e\n```\n\nor this:\n\n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u003e\n    \u003cdestination\u003e\n        destination1.domain.com:4560,\n        destination2.domain.com:4560,\n        destination3.domain.com:4560\n    \u003c/destination\u003e\n\n    ...\n\u003c/appender\u003e\n```\n\nDestinations are expressed using the following format: `host[:port]` where:\n- `host` can be a hostname (eg. `localhost`) , an IPv4 address (eg. `192.168.1.1`) or an IPv6 address enclosed between brackets (eg. `[2001:db8::1]`).\n- `port` is optional and, if specified, must be prefixed by a colon (`:`). It must be a valid integer value between `0` and `65535`.\n\n\nThe appender uses a `connectionStrategy` to determine:\n\n* the order in which destination connections are attempted, and \n* when an established connection should be reestablished (to the next destination selected by the connection strategy).\n\nLogs are only sent to one destination at a time (i.e. not all destinations).\nBy default, the appender will stay connected to the connected destination\nuntil it breaks, or until the application is shut down.\nSome connection strategies can force a reconnect (see below).\nIf a connection breaks, then the appender will attempt to connect\nto the next destination selected by the connection strategy. \n\n\nThe available connection strategies are as follows:\n\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003cth\u003eStrategy\u003c/th\u003e\n      \u003cth\u003eDescription\u003c/th\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003epreferPrimary\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e(default)\nThe first destination is considered the \u003cem\u003eprimary\u003c/em\u003e destination.\nEach additional destination is considered a \u003cem\u003esecondary\u003c/em\u003e destination.\nThis strategy prefers the primary destination, unless it is down.\nThe appender will attempt to connect to each destination in the order in which they are configured.\nIf a connection attempt fails, thes the appender will attempt to connect to the next destination.\nIf a connection succeeds, and then closes \u003cem\u003ebefore\u003c/em\u003e the \u003ctt\u003eminConnectionTimeBeforePrimary\u003c/tt\u003e\nhas elapsed, then the appender will attempt to connect to the next destination.\nIf a connection succeeds, and then closes \u003cem\u003eafter\u003c/em\u003e the \u003ctt\u003eminConnectionTimeBeforePrimary\u003c/tt\u003e\nhas elapsed, then the appender will attempt to connect\nto the destinations in the order in which they are configured,\nstarting at the first/primary destination.\n\u003cbr/\u003e\u003cbr/\u003e\nThe \u003ctt\u003esecondaryConnectionTTL\u003c/tt\u003e can be set to gracefully close connections to \u003cem\u003esecondary\u003c/em\u003e\ndestinations after a specific duration.  This will force the\nthe appender to reattempt to connect to the destinations in order again.\nThe \u003ctt\u003esecondaryConnectionTTL\u003c/tt\u003e value does not affect connections to the\n\u003cem\u003eprimary\u003c/em\u003e destination.\n\u003cbr/\u003e\u003cbr/\u003e\nThe \u003ctt\u003eminConnectionTimeBeforePrimary\u003c/tt\u003e (10 seconds by default) specifies\nthe minimum amount of time that a sucessfully established connection\nmust remain open before the next connection attempt will try the primary.\ni.e. If a connection stays open less than this amount of time,\nthen the next connection attempt will attempt the next destination (instead of the primary).\nThis is used to prevent a connection storm to the primary in the case the\nprimary accepts a connection, and then immediately closes it. \n\u003cbr/\u003e\u003cbr/\u003e\nExample:\n\u003cpre\u003e\n  \u0026lt;appender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u0026gt;\n      \u0026lt;destination\u0026gt;destination1.domain.com:4560\u0026lt;/destination\u0026gt;\n      \u0026lt;destination\u0026gt;destination2.domain.com:4560\u0026lt;/destination\u0026gt;\n      \u0026lt;destination\u0026gt;destination3.domain.com:4560\u0026lt;/destination\u0026gt;\n      \u0026lt;connectionStrategy\u0026gt;\n          \u0026lt;preferPrimary\u0026gt;\n              \u0026lt;secondaryConnectionTTL\u0026gt;5 minutes\u0026lt;/secondaryConnectionTTL\u0026gt;\n          \u0026lt;/preferPrimary\u0026gt;\n      \u0026lt;/connectionStrategy\u0026gt;\n  \u0026lt;/appender\u0026gt;\n\u003c/pre\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003eroundRobin\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\nThis strategy attempts connections to the destination in round robin order.\nIf a connection fails, the next destination is attempted.\n\u003cbr/\u003e\u003cbr/\u003e\nThe \u003ctt\u003econnectionTTL\u003c/tt\u003e can be set to gracefully close connections after a specific duration.\nThis will force the the appender to reattempt to connect to the next destination.\n\u003cbr/\u003e\u003cbr/\u003e\nExample:\n\u003cpre\u003e\n  \u0026lt;appender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u0026gt;\n      \u0026lt;destination\u0026gt;destination1.domain.com:4560\u0026lt;/destination\u0026gt;\n      \u0026lt;destination\u0026gt;destination2.domain.com:4560\u0026lt;/destination\u0026gt;\n      \u0026lt;destination\u0026gt;destination3.domain.com:4560\u0026lt;/destination\u0026gt;\n      \u0026lt;connectionStrategy\u0026gt;\n          \u0026lt;roundRobin\u0026gt;\n              \u0026lt;connectionTTL\u0026gt;5 minutes\u0026lt;/connectionTTL\u0026gt;\n          \u0026lt;/roundRobin\u0026gt;\n      \u0026lt;/connectionStrategy\u0026gt;\n  \u0026lt;/appender\u0026gt;\n\u003c/pre\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003erandom\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\nThis strategy attempts connections to the destination in a random order.\nIf a connection fails, the next random destination is attempted.\n\u003cbr/\u003e\u003cbr/\u003e\nThe \u003ctt\u003econnectionTTL\u003c/tt\u003e can be set to gracefully close connections after a specific duration.\nThis will force the the appender to reattempt to connect to the next random destination.\n\u003cbr/\u003e\u003cbr/\u003e\nExample:\n\u003cpre\u003e\n  \u0026lt;appender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u0026gt;\n      \u0026lt;destination\u0026gt;destination1.domain.com:4560\u0026lt;/destination\u0026gt;\n      \u0026lt;destination\u0026gt;destination2.domain.com:4560\u0026lt;/destination\u0026gt;\n      \u0026lt;destination\u0026gt;destination3.domain.com:4560\u0026lt;/destination\u0026gt;\n      \u0026lt;connectionStrategy\u0026gt;\n          \u0026lt;random\u0026gt;\n              \u0026lt;connectionTTL\u0026gt;5 minutes\u0026lt;/connectionTTL\u0026gt;\n          \u0026lt;/random\u0026gt;\n      \u0026lt;/connectionStrategy\u0026gt;\n  \u0026lt;/appender\u0026gt;\n\u003c/pre\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\nYou can also use your own custom connection strategy by implementing the `DestinationConnectionStrategy` interface,\nand configuring the appender to use it like this:\n\n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u003e\n    \u003cdestination\u003edestination1.domain.com:4560\u003c/destination\u003e\n    \u003cdestination\u003edestination2.domain.com:4560\u003c/destination\u003e\n    \u003cdestination\u003edestination3.domain.com:4560\u003c/destination\u003e\n    \u003cconnectionStrategy class=\"your.package.YourDestinationConnectionStrategy\"\u003e\n    \u003c/connectionStrategy\u003e\n\u003c/appender\u003e\n```\n\n\n#### Reconnection Delay\n\nBy default, the TCP appender will wait 30 seconds between connection attempts to a single destination.\nThe time between connection attempts to each destination is tracked separately.\n\nThis amount of time to delay can be changed by setting the `reconnectionDelay` field.\n\n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u003e\n    ...\n    \u003creconnectionDelay\u003e1 second\u003c/reconnectionDelay\u003e\n\u003c/appender\u003e\n```\n\nThis setting accepts a Logback Duration value - see the section dedicated to [Duration Property](#duration-property) for more information about the valid values.\n\n\n#### Connection Timeout\n\nBy default, a connection timeout of 5 seconds is used when connecting to a remote destination.\nYou can adjust this by setting the appender's `connectionTimeout` configuration property to the desired value.\n\n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u003e\n    ...\n    \u003cconnectionTimeout\u003e5 seconds\u003c/connectionTimeout\u003e\n\u003c/appender\u003e\n```\n\nA value of `0` means \"don't use a timeout and wait indefinitely\" which often really means \"use OS defaults\".\n\nThis setting accepts a Logback Duration value - see the section dedicated to [Duration Property](#duration-property) for more information about the valid values.\n\n\n#### Write Buffer Size\n\nBy default, a buffer size of `8192` bytes is used to buffer socket output stream writes.\nYou can adjust this by setting the appender's `writeBufferSize`.\n \n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u003e\n    ...\n    \u003cwriteBufferSize\u003e16384\u003c/writeBufferSize\u003e\n\u003c/appender\u003e\n```\n\nBuffering can be disabled by setting the `writeBufferSize` to `0`.\nConsider disabling the write buffer if you are concerned about losing data from the buffer for flaky connections.\nDisabling the buffer can potentially slow down the writer thread due to increased system calls,\nbut in some environments, this does not seem to affect overall performance.\nSee [this discussion](https://github.com/logfellow/logstash-logback-encoder/issues/342).\n\n\n#### Write Timeout\n\nIf a destination stops reading from its socket input, but does not close the connection, then writes from the TCP appender will eventually backup, causing the ring buffer to backup, causing events to be dropped.\n\nTo detect this situation, you can enable a write timeout, so that \"stuck\" writes will eventually timeout, at which point the connection will be re-established.\nWhen the [write buffer](#write-buffer-size) is enabled, any buffered data will be lost when the connection is reestablished.\n\nBy default there is no write timeout. To enable a write timeout, do the following:\n\n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u003e\n    ...\n    \u003cwriteTimeout\u003e1 minute\u003c/writeTimeout\u003e\n\u003c/appender\u003e\n```\n\nNote that since the blocking java socket output stream used to send events does not have a concept of a write timeout, write timeouts are detected using a task scheduled periodically with the same frequency as the write timeout.\nFor example, if the write timeout is set to 30 seconds, then a task will execute every 30 seconds to see if 30 seconds has elapsed since the start of the current write operation.\nTherefore, it is recommended to use longer write timeouts (e.g. \u003e 30s, or minutes), rather than short write timeouts, so that this task does not execute too frequently.\nAlso, this approach means that it could take up to two times the write timeout before a write timeout is detected.\n\nThe write timeout must be \u003e0. A timeout of zero is interpreted as an infinite timeout which effecively means \"no write timeout\".\n\nThis setting accepts a Logback Duration value - see the section dedicated to [Duration Property](#duration-property) for more information about the valid values.\n\n\n\n#### Initial Send Delay\n\nThe appender starts writing the events stored in the queue as soon as the connection is established. In some cases you may want to add an extra delay before sending the first events after the connection is established. This may come in handy in situations where the appender connects to an intermediate proxy that needs some time to establish a connection to the final destination. If the appender starts writing immediately, events may be lost in-flight if the proxy ultimately fails to connect to the final destination. \n\nTo enable this feature, set the `initialSendDelay` to the desired delay before the first event is sent after the connection is established. If the connection is lost before the delay expires, no event will be lost. The default value is `0` which means no delay and start flusing pending events immediately.\n\nThe following example configures a delay of 5 secondes before writing in the new connection:\n\n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u003e\n    ...\n    \u003cinitialSendDelay\u003e5 secondes\u003c/initialSendDelay\u003e\n\u003c/appender\u003e\n```\n\nThis setting accepts a Logback Duration value - see the section dedicated to [Duration Property](#duration-property) for more information about the valid values.\n\n\n#### SSL\n\nTo use SSL, add an `\u003cssl\u003e` sub-element within the `\u003cappender\u003e` element for the `LogstashTcpSocketAppender`\nor `LogstashAccessTcpSocketAppender`.\n\nSee the [logback manual](http://logback.qos.ch/manual/usingSSL.html) for how to configure SSL.\nSSL for the `Logstash*TcpSocketAppender`s are configured the same way as logback's `SSLSocketAppender`.\n\nFor example, to enable SSL using the JVM's default keystore/truststore, do the following:\n\n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashTcpSocketAppender\"\u003e\n    ...\n\n    \u003c!-- Enable SSL using the JVM's default keystore/truststore --\u003e\n    \u003cssl/\u003e\n\u003c/appender\u003e\n```\n\nTo use a different truststore, do the following:\n\n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashAccessTcpSocketAppender\"\u003e\n    ...\n\n    \u003c!-- Enable SSL and use a different truststore --\u003e\n    \u003cssl\u003e\n        \u003ctrustStore\u003e\n            \u003clocation\u003eclasspath:server.truststore\u003c/location\u003e\n            \u003cpassword\u003e${server.truststore.password}\u003c/password\u003e\n        \u003c/trustStore\u003e\n    \u003c/ssl\u003e\n\u003c/appender\u003e\n```\n\nAll the customizations that [logback](http://logback.qos.ch/manual/usingSSL.html) offers\n(such as configuring cipher specs, protocols, algorithms, providers, etc.)\nare supported by the `Logback*TcpSocketAppender`s.\n\nSee the logstash documentation for the [`tcp`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-tcp.html) input for how to configure it to use SSL.\n\n\n### Async Appenders\n\nThe `*AsyncDisruptorAppender` appenders are similar to logback's `AsyncAppender`,\nexcept that a [LMAX Disruptor RingBuffer](https://lmax-exchange.github.io/disruptor/)\nis used as the queuing mechanism, as opposed to a `BlockingQueue`.\nThese async appenders can delegate to any other underlying logback appender.\n\nFor example:\n\n```xml\n\u003cappender name=\"file\" class=\"ch.qos.logback.core.rolling.RollingFileAppender\"\u003e\n    ...\n\u003c/appender\u003e\n    \n\u003cappender name=\"async\" class=\"net.logstash.logback.appender.LoggingEventAsyncDisruptorAppender\"\u003e\n    \u003cappender-ref ref=\"file\" /\u003e\n\u003c/appender\u003e\n```\n\n\u003e [!WARNING]\n\u003e Logback 1.3 no longer allows declaring an `\u003cappender\u003e` inside another `\u003cappender\u003e`.\n\u003e The nested appender should instead be declared outside and `\u003cappender-ref\u003e` must be used to refer to it.\n\u003e \n\u003e See [LOGBACK-1674](https://jira.qos.ch/browse/LOGBACK-1674) for more information.\n\n\n#### RingBuffer Size\n\nLogging events are first enqueued in a ring buffer before they are delivered to their final destination by a separate handler thread.\nThe buffer size is fixed, it does not grow or shrink at runtime. Its size is determined  by the `ringBufferSize` configuration property set to `8192` by default.\n\nIf the handler thread is not as fast as the producing threads, then the ring buffer will eventually fill up, at which point events will be dropped (the default) or the producing threads are blocked depending on configured `appendTimeout` (see [RingBuffer Full](#ringbuffer-full).\n\n\n#### RingBuffer Full\n\nThe async appenders will by default never block the logging thread.\nIf the RingBuffer is full (e.g. due to slow network, etc), then events will be dropped.\n\nAlternatively, you can configure the appender to wait until space becomes available instead of dropping the events immediately. This may come in handy when you want to rely on the buffering and the async nature of the appender but don't want to loose any event in case of large logging bursts that exceed the size of the RingBuffer.\n\nThe behaviour of the appender when the RingBuffer is controlled by the `appendTimeout` configuration property:\n\n| `appendTimeout` | Behaviour when RingBuffer is full                                      |\n|-----------------|------------------------------------------------------------------------|\n| `\u003c 0`           | disable timeout and wait until space is available                      |\n| `0`             | no timeout, give up immediately and drop event (this is the *default*) |\n| `\u003e 0`           | retry during the specified amount of time                              |\n\n\nLogging threads waiting for space in the RingBuffer wake up periodically at a frequency starting at `1ns` and increasing exponentially up to `appendRetryFrequency` (default `5ms`). \nOnly one thread is allowed to retry at a time. If a thread is already retrying, additional threads are waiting on a lock until the first is finished. This strategy should help to limit CPU consumption while providing good enough latency and throughput when the ring buffer is at (or close) to its maximal capacity.\n\nWhen the appender drops an event, it emits a warning status message every `droppedWarnFrequency` consecutive dropped events (`1000` by default, use `0` to turn off warnings). Another status message is emitted when the drop period is over and a first event is succesfully enqueued reporting the total number of events that were dropped.\n\n\n#### Graceful Shutdown\n\nTo guarantees that logged messages have had a chance to be processed by asynchronous appenders (including the TCP appender) and ensure background threads have been stopped, you'll need to [cleanly shut down logback](http://logback.qos.ch/manual/configuration.html#stopContext) when your application exits.\n\nWhen gracefully stopped, async appenders wait until all events in the buffer are processed and the buffer is empty.\nThe maximum time to wait is configured by the `shutdownGracePeriod` parameter and is set to `1 minute` by default.\nEvents still in the buffer after this period is elapsed are dropped and the appender is stopped.\n\n\n#### Wait Strategy\n\nBy default, the [`BlockingWaitStrategy`](https://lmax-exchange.github.io/disruptor/docs/com/lmax/disruptor/BlockingWaitStrategy.html) is used by the worker thread spawned by this appender.\nThe `BlockingWaitStrategy` minimizes CPU utilization, but results in slower latency and throughput.\nIf you need faster latency and throughput (at the expense of higher CPU utilization), consider\na different [wait strategy](https://lmax-exchange.github.io/disruptor/docs/com/lmax/disruptor/WaitStrategy.html) offered by the disruptor.\n\n\u003e [!IMPORTANT]\n\u003e Whichever wait strategy you choose, be sure to test and monitor CPU utilization, latency, and throughput to ensure it meets your needs.\n\u003e For example, in some configurations, `SleepingWaitStrategy` can consume 90% CPU utilization at rest.\n\nThe wait strategy can be configured on the async appender using the `waitStrategyType` parameter, like this:\n\n```xml\n\u003cappender name=\"async\" class=\"net.logstash.logback.appender.LoggingEventAsyncDisruptorAppender\"\u003e\n    \u003cwaitStrategyType\u003esleeping\u003c/waitStrategyType\u003e\n    ...\n\u003c/appender\u003e\n```\n\nThe supported wait strategies are as follows:\n\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003cth\u003eWait Strategy\u003c/th\u003e\n      \u003cth\u003eParameters\u003c/th\u003e\n      \u003cth\u003eImplementation\u003c/th\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ctt\u003eblocking\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003enone\u003c/td\u003e\n      \u003ctd\u003e\u003ca href=\"https://lmax-exchange.github.io/disruptor/docs/com/lmax/disruptor/BlockingWaitStrategy.html\"\u003e\u003ctt\u003eBlockingWaitStrategy\u003c/tt\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ctt\u003ebusySpin\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003enone\u003c/td\u003e\n      \u003ctd\u003e\u003ca href=\"https://lmax-exchange.github.io/disruptor/docs/com/lmax/disruptor/BusySpinWaitStrategy.html\"\u003e\u003ctt\u003eBusySpinWaitStrategy\u003c/tt\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ctt\u003eliteBlocking\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003enone\u003c/td\u003e\n      \u003ctd\u003e\u003ca href=\"https://lmax-exchange.github.io/disruptor/docs/com/lmax/disruptor/LiteBlockingWaitStrategy.html\"\u003e\u003ctt\u003eLiteBlockingWaitStrategy\u003c/tt\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ctt\u003eyielding\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003enone\u003c/td\u003e\n      \u003ctd\u003e\u003ca href=\"https://lmax-exchange.github.io/disruptor/docs/com/lmax/disruptor/YieldingWaitStrategy.html\"\u003e\u003ctt\u003eYieldingWaitStrategy\u003c/tt\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003cpre\u003esleeping{\n  \u003cem\u003eretries\u003c/em\u003e,\n  \u003cem\u003esleepTimeNs\u003c/em\u003e\n}\n\u003c/pre\u003ee.g.\u003cbr/\u003e\u003ctt\u003esleeping\u003c/tt\u003e\u003cbr/\u003eor\u003cbr/\u003e\u003ctt\u003esleeping{500,1000}\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003col\u003e\n          \u003cli\u003e\u003ctt\u003eretries\u003c/tt\u003e - Number of times (integer) to spin before sleeping. (default = 200)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003esleepTimeNs\u003c/tt\u003e - Time in nanoseconds to sleep each iteration after spinning (default = 100)\u003c/li\u003e\n        \u003c/ol\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\u003ca href=\"https://lmax-exchange.github.io/disruptor/docs/com/lmax/disruptor/SleepingWaitStrategy.html\"\u003e\u003ctt\u003eSleepingWaitStrategy\u003c/tt\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003cpre\u003ephasedBackoff{\n  \u003cem\u003espinTime\u003c/em\u003e,\n  \u003cem\u003eyieldTime\u003c/em\u003e,\n  \u003cem\u003etimeUnit\u003c/em\u003e,\n  \u003cem\u003efallbackStrategy\u003c/em\u003e\n}\n\u003c/pre\u003e\ne.g.\u003cbr/\u003e\u003ctt\u003ephasedBackoff{10,60,seconds,blocking}\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003col\u003e\n          \u003cli\u003e\u003ctt\u003espinTime\u003c/tt\u003e - Time to spin before yielding\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003eyieldTime\u003c/tt\u003e - Time to yield before falling back to the \u003ctt\u003efallbackStrategy\u003c/tt\u003e\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003etimeUnit\u003c/tt\u003e - Units of time for spin and yield timeouts. String name of a \u003ca href=\"http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/TimeUnit.html\"\u003e\u003ctt\u003eTimeUnit\u003c/tt\u003e\u003c/a\u003e value (e.g. \u003ctt\u003eseconds\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003efallbackStrategy\u003c/tt\u003e - String name of the wait strategy to fallback to after the timeouts have elapsed\u003c/li\u003e\n        \u003c/ol\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\u003ca href=\"https://lmax-exchange.github.io/disruptor/docs/com/lmax/disruptor/PhasedBackoffWaitStrategy.html\"\u003e\u003ctt\u003ePhasedBackoffWaitStrategy\u003c/tt\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003cpre\u003etimeoutBlocking{\n  \u003cem\u003etimeout\u003c/em\u003e,\n  \u003cem\u003etimeUnit\u003c/em\u003e\n}\n\u003c/pre\u003ee.g.\u003cbr/\u003e\u003ctt\u003etimeoutBlocking{1,minutes}\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003col\u003e\n          \u003cli\u003e\u003ctt\u003etimeout\u003c/tt\u003e - Time to block before throwing an exception\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003etimeUnit\u003c/tt\u003e - Units of time for timeout. String name of a \u003ca href=\"http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/TimeUnit.html\"\u003e\u003ctt\u003eTimeUnit\u003c/tt\u003e\u003c/a\u003e value (e.g. \u003ctt\u003eseconds\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ol\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\u003ca href=\"https://lmax-exchange.github.io/disruptor/docs/com/lmax/disruptor/TimeoutBlockingWaitStrategy.html\"\u003e\u003ctt\u003eTimeoutBlockingWaitStrategy\u003c/tt\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003cpre\u003eliteTimeoutBlocking{\n  \u003cem\u003etimeout\u003c/em\u003e,\n  \u003cem\u003etimeUnit\u003c/em\u003e\n}\n\u003c/pre\u003ee.g.\u003cbr/\u003e\u003ctt\u003eliteTimeoutBlocking{1,minutes}\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003col\u003e\n          \u003cli\u003e\u003ctt\u003etimeout\u003c/tt\u003e - Time to block before throwing an exception\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003etimeUnit\u003c/tt\u003e - Units of time for timeout. String name of a \u003ca href=\"http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/TimeUnit.html\"\u003e\u003ctt\u003eTimeUnit\u003c/tt\u003e\u003c/a\u003e value (e.g. \u003ctt\u003eseconds\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ol\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\u003ca href=\"https://lmax-exchange.github.io/disruptor/docs/com/lmax/disruptor/LiteTimeoutBlockingWaitStrategy.html\"\u003e\u003ctt\u003eLiteTimeoutBlockingWaitStrategy\u003c/tt\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\nSee [AsyncDisruptorAppender](/src/main/java/net/logstash/logback/appender/AsyncDisruptorAppender.java)\nfor other configuration parameters (such as `ringBufferSize`, `threadNamePrefix`, `daemon`, and `droppedWarnFrequency`)\n\n\n### Appender Listeners\n\nListeners can be registered to an appender to receive notifications for the appender lifecycle and event processing.\n\nSee the two listener interfaces for the types of notifications that can be received:\n\n* [`AppenderListener`](/src/main/java/net/logstash/logback/appender/listener/AppenderListener.java) - basic notifications for the [async appenders](#async-appenders) and [UDP appenders](#udp-appenders).\n* [`TcpAppenderListener`](/src/main/java/net/logstash/logback/appender/listener/TcpAppenderListener.java) - extension of `AppenderListener` with additional TCP-specific notifications.  Only works with the [TCP appenders](#tcp-appenders). \n\nSome example use cases for a listener are:\n\n* Monitoring metrics for events per second, event processing durations, dropped events, connections successes / failures, etc.\n* Logging event processing errors to a different appender (that perhaps appends to a different destination).\n  \nA [`FailureSummaryLoggingAppenderListener`](src/main/java/net/logstash/logback/appender/listener/FailureSummaryLoggingAppenderListener.java)\nis provided that will log a warning on the first success after a series of consecutive append/send/connect failures.\nThe message includes summary details of the failures that occurred (such as the number of failures, duration of the failures, etc).\nTo register it:\n\n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashAccessTcpSocketAppender\"\u003e\n    \u003clistener class=\"net.logstash.logback.appender.listener.FailureSummaryLoggingAppenderListener\"\u003e\n        \u003cloggerName\u003enet.logstash.logback.appender.listener.FailureSummaryLoggingAppenderListener\u003c/loggerName\u003e\n    \u003c/listener\u003e\n\u003c/appender\u003e\n```\n\nYou may also create your own listener by implementing the `*Listener` interface and register it to an appender using the `listener` xml element like this:\n\n```xml\n\u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashAccessTcpSocketAppender\"\u003e\n    ...\n\n    \u003clistener class=\"your.package.YourListenerClass\"\u003e\n        \u003cyourListenerProperty\u003epropertyValue\u003c/yourListenerProperty\u003e\n    \u003c/listener\u003e\n\u003c/appender\u003e\n```\n\nMultiple listeners can be registered by supplying multiple `listener` xml elements.\n\n\n### Encoders / Layouts\n\nYou can use any of the encoders/layouts provided by the logstash-logback-encoder library with other logback appenders.\n\nFor example, to output LoggingEvents to a file, use the `LogstashEncoder`\nwith the `RollingFileAppender` in your `logback.xml` like this:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cconfiguration\u003e\n    \u003cappender name=\"stash\" class=\"ch.qos.logback.core.rolling.RollingFileAppender\"\u003e\n        \u003cfilter class=\"ch.qos.logback.classic.filter.ThresholdFilter\"\u003e\n            \u003clevel\u003einfo\u003c/level\u003e\n        \u003c/filter\u003e\n        \u003cfile\u003e/some/path/to/your/file.log\u003c/file\u003e\n        \u003crollingPolicy class=\"ch.qos.logback.core.rolling.TimeBasedRollingPolicy\"\u003e\n            \u003cfileNamePattern\u003e/some/path/to/your/file.log.%d{yyyy-MM-dd}\u003c/fileNamePattern\u003e\n            \u003cmaxHistory\u003e30\u003c/maxHistory\u003e\n        \u003c/rollingPolicy\u003e\n        \u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\" /\u003e\n    \u003c/appender\u003e\n    \n    \u003croot level=\"all\"\u003e\n        \u003cappender-ref ref=\"stash\" /\u003e\n    \u003c/root\u003e\n\u003c/configuration\u003e\n```\n\nTo log AccessEvents to a file, configure your `logback-access.xml` like this:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cconfiguration\u003e\n    \u003cappender name=\"stash\" class=\"ch.qos.logback.core.rolling.RollingFileAppender\"\u003e\n        \u003cfile\u003e/some/path/to/your/file.log\u003c/file\u003e\n        \u003cencoder class=\"net.logstash.logback.encoder.LogstashAccessEncoder\" /\u003e\n    \u003c/appender\u003e\n\n    \u003cappender-ref ref=\"stash\" /\u003e\n\u003c/configuration\u003e\n```\n\nThe `LogstashLayout` and `LogstashAccessLayout` can be configured the same way as\nthe `LogstashEncoder` and `LogstashAccessEncoder`.  All the other examples\nin this document use encoders, but the same options apply to the layouts as well.\n\nTo receive file input in logstash, configure a [`file`](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-file.html) input in logstash's configuration like this:\n\n```\ninput {\n    file {\n        path =\u003e \"/some/path/to/your/file.log\"\n        codec =\u003e \"json\"\n    }\n}\n```\n\n### Threads and ThreadLocals\n\nAsynchronous appenders use a separate set of threads to process logging events.\n\nThe encoders/layouts use ThreadLocals internally to improve performance.\n\nIn environments that support application reloading (e.g. web containers)\nand in applications with many threads logging events (e.g. virtual threads),\nit is recommended to:\n1. use an asynchronous appender (such as `LogstashTcpSocketAppender`, `LoggingEventAsyncDisruptorAppender`, or [`AsyncAppender`](https://logback.qos.ch/manual/appenders.html#AsyncAppender)), and\n2. [cleanly shut down logback](http://logback.qos.ch/manual/configuration.html#stopContext) when the application is stopped/reloaded.\n\n\nUsing an asynchronous appender ensures that a limited number of threads use the encoder/layout,\nand therefore limits the number of ThreadLocal value instances\nand minimizes resource contention.\n\nCleanly shutting down logback stops the threads used by the asynchronous appender,\nand makes their ThreadLocal values eligible for garbage collection.\n\nFailure to use an asynchronous appender may result in errors like the following when stopping/reloading an application in Tomcat:\n\n```\nThe web application [webapp] created a ThreadLocal with key of type [java.lang.ThreadLocal.SuppliedThreadLocal]\n(value [java.lang.ThreadLocal$SuppliedThreadLocal@6f75b07c]) and a value of type\n[net.logstash.logback.util.ThreadLocalHolder.Holder] (value [net.logstash.logback.util.ThreadLocalHolder$Holder@7d940c3e])\nbut failed to remove it when the web application was stopped.\nThreads are going to be renewed over time to try and avoid a probable memory leak.\n```\n\nFailure to cleanly shutdown logback may result in errors like the following when stopping/reloading an application in Tomcat:\n\n```\nThe web application [webapp] appears to have started a thread named [logback-appender-ASYNC-2] but has failed to stop it.\nThis is very likely to create a memory leak.\n```\n\n## LoggingEvent Fields\n\nThe following sections describe the fields included in the JSON output by default for LoggingEvents written by the\n\n* `LogstashEncoder`\n* `LogstashLayout`, and\n* the logstash appenders\n\nIf you are using the [composite encoders/layouts](#composite-encoderlayout), then the fields written will\nvary by the providers you configure.\n\n\n### Standard Fields\n\nThese fields will appear in every LoggingEvent unless otherwise noted.\nThe field names listed here are the default field names.\nThe field names can be customized (see [Customizing Standard Field Names](#customizing-standard-field-names)).\n\n| Field         | Description                                                                                                                                                                                                                                                                                                                                                                       |\n|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `@timestamp`  | Time of the log event (`ISO_OFFSET_DATE_TIME`) - see [Customizing Timestamp](#customizing-timestamp)                                                                                                                                                                                                                                                                              |\n| `@version`    | Logstash format version (e.g. `1`) - see [Customizing Version](#customizing-version)                                                                                                                                                                                                                                                                                              |\n| `message`     | Formatted log message of the event - see [Customizing Message](#customizing-message)                                                                                                                                                                                                                                                                                              |\n| `logger_name` | Name of the logger that logged the event                                                                                                                                                                                                                                                                                                                                          |\n| `thread_name` | Name of the thread that logged the event                                                                                                                                                                                                                                                                                                                                          |\n| `level`       | String name of the level of the event                                                                                                                                                                                                                                                                                                                                             |\n| `level_value` | Integer value of the level of the event                                                                                                                                                                                                                                                                                                                                           |\n| `stack_trace` | (Only if a throwable was logged) The stacktrace of the throwable.  Stackframes are separated by line endings.                                                                                                                                                                                                                                                                     |\n| `tags`        | (Only if tags are found) The names of any markers not explicitly handled.  (e.g. markers from `MarkerFactory.getMarker` will be included as tags, but the markers from [`Markers`](/src/main/java/net/logstash/logback/marker/Markers.java) will not.) This can be fully disabled by specifying `\u003cincludeTags\u003efalse\u003c/includeTags\u003e`, in the encoder/layout/appender configuration. |\n\n### MDC fields\n\nBy default, `LogstashEncoder`/`LogstashLayout` will write each\n[Mapped Diagnostic Context (MDC) (`org.slf4j.MDC`)](https://www.slf4j.org/api/org/slf4j/MDC.html)\nentry to the output.\n\nTo disable writing MDC entries, add `\u003cincludeMdc\u003efalse\u003c/includeMdc\u003e`\nto the `LogstashEncoder`/`LogstashLayout` configuration.\n\nYou can also configure specific entries in the MDC to be included or excluded as follows:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cincludeMdcKeyName\u003ekey1ToInclude\u003c/includeMdcKeyName\u003e\n    \u003cincludeMdcKeyName\u003ekey2ToInclude\u003c/includeMdcKeyName\u003e\n\u003c/encoder\u003e\n```\n\nor\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cexcludeMdcKeyName\u003ekey1ToExclude\u003c/excludeMdcKeyName\u003e\n    \u003cexcludeMdcKeyName\u003ekey2ToExclude\u003c/excludeMdcKeyName\u003e\n\u003c/encoder\u003e\n```\n\nWhen key names are specified for inclusion, then all other fields will be excluded.\nWhen key names are specified for exclusion, then all other fields will be included.\nIt is a configuration error to specify both included and excluded key names.\n\nBy default, the MDC key is used as the field name in the output.\nTo use an alternative field name in the output for an MDC entry,\nspecify `\u003cmdcKeyFieldName\u003emdcKeyName=fieldName\u003c/mdcKeyFieldName\u003e`: \n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cmdcKeyFieldName\u003ekey1=alternateFieldNameForKey1\u003c/mdcKeyFieldName\u003e\n\u003c/encoder\u003e\n```\n\nYou can also manipulate the MDC entry values written to the JSON output.\nBy default, no manipulations are done and all MDC entry values are written as text.\n\nCurrently, the following MDC entry writers are supported:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003c!--\n        Writes long values (instead of String values) for any MDC values\n        that can be parsed as a long (radix 10).\n        e.g. Writes 1234 instead of \"1234\"\n    --\u003e\n    \u003cmdcEntryWriter class=\"net.logstash.logback.composite.loggingevent.mdc.LongMdcEntryWriter\"/\u003e\n\n    \u003c!--\n        Writes double values (instead of String values) for any MDC values\n        that can be parsed as a double, except NaN and positive/negative Infinity.\n        e.g. 1234.5678 instead of \"1234.5678\"\n    --\u003e\n    \u003cmdcEntryWriter class=\"net.logstash.logback.composite.loggingevent.mdc.DoubleMdcEntryWriter\"/\u003e\n\n    \u003c!--\n        Writes boolean values (instead of String values) for any MDC values\n        that equal \"true\" or \"false\", ignoring case.\n        e.g. Writes true instead of \"true\"\n    --\u003e\n    \u003cmdcEntryWriter class=\"net.logstash.logback.composite.loggingevent.mdc.BooleanMdcEntryWriter\"/\u003e\n\n    \u003c!--\n        Composite MDC entry writer that delegates writing MDC entries to a list of `MdcEntryWriter`\n        if the key of an MDC entry does match a given include pattern and does not match a given\n        exclude pattern.\n                \n        Omitting the 'includeMdcKeyPattern' means to include all MDC keys.\n        Omitting the 'excludeMdcKeyPattern' means to exclude no MDC keys.\n        \n        The elements with the key patterns are optional. If provided, use a regular expression\n        with the syntax of `java.util.regex.Pattern`.\n    --\u003e\n    \u003cmdcEntryWriter class=\"net.logstash.logback.composite.loggingevent.mdc.RegexFilteringMdcEntryWriter\"\u003e\n        \u003cincludeMdcKeyPattern\u003ekeyPatternToInclude\u003c/includeMdcKeyPattern\u003e\n        \u003cexcludeMdcKeyPattern\u003ekeyPatternToExclude\u003c/excludeMdcKeyPattern\u003e\n        \u003cmdcEntryWriter class=\"net.logstash.logback.composite.loggingevent.LongMdcEntryWriter\"/\u003e\n    \u003c/mdcEntryWriter\u003e\n\u003c/encoder\u003e\n```\n\nTo add your own MDC entry writer for other types or apply the manipulations only for specific fields\nyou can write your own implementation of [`MdcEntryWriter`](src/main/java/net/logstash/logback/composite/loggingevent/mdc/MdcEntryWriter.java).\n\nYou can also replace the default MDC JSON provider with your own class extending from\n[`MdcJsonProvider`](src/main/java/net/logstash/logback/composite/loggingevent/MdcJsonProvider.java).\nConfiguring your class as a [Custom JSON Provider](#custom-json-provider) will then replace\nthe default `MdcJsonProvider`.\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cprovider class=\"mypackagenames.MyCustomMdcJsonProvider\"/\u003e\n\u003c/encoder\u003e\n```\n\n\n### Key Value Pair Fields\n\nSlf4j 2's [fluent API](https://www.slf4j.org/manual.html#fluent) supports attaching key value pairs to the log event.\n\n`LogstashEncoder`/`LogstashLayout` will write each key value pair as a field in the output by default.\n\nTo disable writing key value pairs, add `\u003cincludeKeyValuePairs\u003efalse\u003c/includeKeyValuePairs\u003e`\nto the `LogstashEncoder`/`LogstashLayout` configuration.\n\nYou can also configure specific key value pairs to be included or excluded as follows:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cincludeKeyValueKeyName\u003ekey1ToInclude\u003c/includeKeyValueKeyName\u003e\n    \u003cincludeKeyValueKeyName\u003ekey2ToInclude\u003c/includeKeyValueKeyName\u003e\n\u003c/encoder\u003e\n```\n\nor\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cexcludeKeyValueKeyName\u003ekey1ToExclude\u003c/excludeKeyValueKeyName\u003e\n    \u003cexcludeKeyValueKeyName\u003ekey2ToExclude\u003c/excludeKeyValueKeyName\u003e\n\u003c/encoder\u003e\n```\n\nWhen key names are specified for inclusion, then all other keys will be excluded.\nWhen key names are specified for exclusion, then all other keys will be included.\nIt is a configuration error to specify both included and excluded key names.\n\nBy default, the key is used as the field name in the output.\nTo use an alternative field name in the output for an key value pair,\nspecify`\u003ckeyValuePairsKeyFieldName\u003ekeyName=fieldName\u003c/keyValuePairsKeyFieldName\u003e`: \n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003ckeyValueKeyFieldName\u003ekey1=alternateFieldNameForKey1\u003c/keyValueKeyFieldName\u003e\n\u003c/encoder\u003e\n```\n\n\n### Context fields\n\nBy default, each property of Logback's Context (`ch.qos.logback.core.Context`)\nwill appear as a field in the LoggingEvent.\nThis can be disabled by specifying `\u003cincludeContext\u003efalse\u003c/includeContext\u003e`\nin the encoder/layout/appender configuration.\n\nNote that logback versions prior to 1.1.10 included a `HOSTNAME` property by default in the context.\nAs of logback 1.1.10, the `HOSTNAME` property is lazily calculated (see [LOGBACK-1221](https://jira.qos.ch/browse/LOGBACK-1221)), and will no longer be included by default.\n\n\n### Caller Info Fields\nThe encoder/layout/appender do not contain caller info by default.\nThis can be costly to calculate and should be switched off for busy production environments.\n\nTo switch it on, add the `includeCallerData` property to the configuration.\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cincludeCallerData\u003etrue\u003c/includeCallerData\u003e\n\u003c/encoder\u003e\n```\nIf the encoder is included inside an asynchronous appender, such as\n`AsyncAppender`, `LoggingEventAsyncDisruptorAppender`, or `LogstashTcpSocketAppender`, then\n`includeCallerData` must be set to true on the appender as well.\n\nWhen switched on, the following fields will be included in the log event:\n\n| Field                | Description                                                   |\n|----------------------|---------------------------------------------------------------|\n| `caller_class_name`  | Fully qualified class name of the class that logged the event |\n| `caller_method_name` | Name of the method that logged the event                      |\n| `caller_file_name`   | Name of the file that logged the event                        |\n| `caller_line_number` | Line number of the file where the event was logged            |\n\n### Custom Fields\n\nIn addition to the fields above, you can add other fields to the LoggingEvent either globally, or on an event-by-event basis.\n\n\n#### Global Custom Fields\n\nAdd custom fields that will appear in every LoggingEvent like this :\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003ccustomFields\u003e{\"appname\":\"myWebservice\",\"roles\":[\"customerorder\",\"auth\"],\"buildinfo\":{\"version\":\"Version 0.1.0-SNAPSHOT\",\"lastcommit\":\"75473700d5befa953c45f630c6d9105413c16fe1\"}}\u003c/customFields\u003e\n\u003c/encoder\u003e\n```\n\nor in an AccessEvent like this :\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashAccessEncoder\"\u003e\n    \u003ccustomFields\u003e{\"appname\":\"myWebservice\",\"roles\":[\"customerorder\",\"auth\"],\"buildinfo\":{\"version\":\"Version 0.1.0-SNAPSHOT\",\"lastcommit\":\"75473700d5befa953c45f630c6d9105413c16fe1\"}}\u003c/customFields\u003e\n\u003c/encoder\u003e\n```\n\n\n\n#### Event-specific Custom Fields\n\nWhen logging a message, you can add additional fields to the JSON output by using\n\n* (recommended) slf4j's [fluent API](https://www.slf4j.org/manual.html#fluent) for attaching key value pairs to the log event.\n  see [Key Value Pair Fields](#key-value-pair-fields).\n* _structured arguments_ provided by\n  [`StructuredArguments`](/src/main/java/net/logstash/logback/argument/StructuredArguments.java), OR\n* _markers_ provided by\n  [`Markers`](/src/main/java/net/logstash/logback/marker/Markers.java)\n\nThe difference between structured arguments and markers is that\n* `StructuredArguments` are included in the log event's formatted message\n(when the message has a parameter for the argument) _AND_ in the JSON output.\n  * `StructuredArguments` will be included in the JSON output if using `LogstashEncoder/Layout`\n    or if using [composite encoders/layouts](#composite-encoderlayout) with the `arguments` provider.\n* `Markers` are only written to the JSON output, and _NEVER_ to the log event's formatted message.\n  * `Markers` will be included in the JSON output if using `LogstashEncoder/Layout`\n    or if using [composite encoders/layouts](#composite-encoderlayout) with the `logstashMarkers` provider.\n\n\nYou can use `StructuredArguments` even if the message does not contain a parameter\nfor the argument.  However, in this case, the argument will only be written to the JSON output\nand not the formatted message (which is effectively the same behavior that the Markers provide).\nIn general, you should use `StructuredArguments`, unless you have a static analyzer\nthat flags parameter count / argument count mismatches.\n\nBoth `StructuredArguments` and `Markers` require constructing additional objects.\nTherefore, it is best practice to surround the log lines with `logger.isXXXEnabled()`,\nto avoid the object construction if the log level is disabled.\n\nExamples using `StructuredArguments`:\n\n```java\nimport static net.logstash.logback.argument.StructuredArguments.*;\n\n/*\n * Add \"name\":\"value\" to the JSON output,\n * but only add the value to the formatted message.\n *\n * The formatted message will be `log message value`\n */\nlogger.info(\"log message {}\", value(\"name\", \"value\"));\n\n/*\n * Add \"name\":\"value\" to the JSON output,\n * and add name=value to the formatted message.\n *\n * The formatted message will be `log message name=value`\n */\nlogger.info(\"log message {}\", keyValue(\"name\", \"value\"));\n\n/*\n * Add \"name\":\"value\" ONLY to the JSON output.\n *\n * Since there is no parameter for the argument,\n * the formatted message will NOT contain the key/value.\n *\n * If this looks funny to you or to static analyzers,\n * consider using Markers instead.\n */\nlogger.info(\"log message\", keyValue(\"name\", \"value\"));\n\n/*\n * Add multiple key value pairs to both JSON and formatted message\n */\nlogger.info(\"log message {} {}\", keyValue(\"name1\", \"value1\"), keyValue(\"name2\", \"value2\")));\n\n/*\n * Add \"name\":\"value\" to the JSON output and\n * add name=[value] to the formatted message using a custom format.\n */\nlogger.info(\"log message {}\", keyValue(\"name\", \"value\", \"{0}=[{1}]\"));\n\n/*\n * In the JSON output, values will be serialized by Jackson's ObjectMapper.\n * In the formatted message, values will follow the same behavior as logback\n * (formatting of an array or if not an array `toString()` is called).\n *\n * Add \"foo\":{...} to the JSON output and add `foo.toString()` to the formatted message:\n *\n * The formatted message will be `log message \u003cresult of foo.toString()\u003e`\n */\nFoo foo  = new Foo();\nlogger.info(\"log message {}\", value(\"foo\", foo));\n\n/*\n * Add \"name1\":\"value1\",\"name2\":\"value2\" to the JSON output by using a Map,\n * and add `myMap.toString()` to the formatted message.\n *\n * Note the values can be any object that can be serialized by Jackson's ObjectMapper\n * (e.g. other Maps, JsonNodes, numbers, arrays, etc)\n */\nMap myMap = new HashMap();\nmyMap.put(\"name1\", \"value1\");\nmyMap.put(\"name2\", \"value2\");\nlogger.info(\"log message {}\", entries(myMap));\n\n/*\n * Add \"array\":[1,2,3] to the JSON output,\n * and array=[1,2,3] to the formatted message.\n */\nlogger.info(\"log message {}\", array(\"array\", 1, 2, 3));\n\n/*\n * Add fields of any object that can be unwrapped by Jackson's UnwrappableBeanSerializer to the JSON output.\n * i.e. The fields of an object can be written directly into the JSON output.\n * This is similar to the @JsonUnwrapped annotation.\n *\n * The formatted message will contain `myobject.toString()`\n */\nlogger.info(\"log message {}\", fields(myobject));\n\n/*\n * In order to normalize a field object name, static helper methods can be created.\n * For example:\n *     public static StructuredArgument foo(Foo foo) {\n *         return StructuredArguments.value(\"foo\", foo);\n *     }\n */\nlogger.info(\"log message {}\", foo(foo));\n\n```\n\nAbbreviated convenience methods are available for all the structured argument types.\nFor example, instead of `keyValue(key, value)`, you can use `kv(key, value)`.\n\n\n\nExamples using `Markers`:\n\n```java\nimport static net.logstash.logback.marker.Markers.*;\n\n/*\n * Add \"name\":\"value\" to the JSON output.\n */\nlogger.info(append(\"name\", \"value\"), \"log message\");\n\n/*\n * Add \"name1\":\"value1\",\"name2\":\"value2\" to the JSON output by using multiple markers.\n */\nlogger.info(append(\"name1\", \"value1\").and(append(\"name2\", \"value2\")), \"log message\");\n\n/*\n * Add \"name1\":\"value1\",\"name2\":\"value2\" to the JSON output by using a map.\n *\n * Note the values can be any object that can be serialized by Jackson's ObjectMapper\n * (e.g. other Maps, JsonNodes, numbers, arrays, etc)\n */\nMap myMap = new HashMap();\nmyMap.put(\"name1\", \"value1\");\nmyMap.put(\"name2\", \"value2\");\nlogger.info(appendEntries(myMap), \"log message\");\n\n/*\n * Add \"array\":[1,2,3] to the JSON output\n */\nlogger.info(appendArray(\"array\", 1, 2, 3), \"log message\");\n\n/*\n * Add \"array\":[1,2,3] to the JSON output by using raw json.\n * This allows you to use your own json seralization routine to construct the json output\n */\nlogger.info(appendRaw(\"array\", \"[1,2,3]\"), \"log message\");\n\n/*\n * Add any object that can be serialized by Jackson's ObjectMapper\n * (e.g. Maps, JsonNodes, numbers, arrays, etc)\n */\nlogger.info(append(\"object\", myobject), \"log message\");\n\n/*\n * Add fields of any object that can be unwrapped by Jackson's UnwrappableBeanSerializer.\n * i.e. The fields of an object can be written directly into the json output.\n * This is similar to the @JsonUnwrapped annotation.\n */\nlogger.info(appendFields(myobject), \"log message\");\n\n```\n\n\n## AccessEvent Fields\n\nThe following sections describe the fields included in the JSON output by default for AccessEvents written by the\n\n* `LogstashAccessEncoder`,\n* `LogstashAccessLayout`, and\n* the logstash access appenders.\n\nIf you are using the [composite encoders/layouts](#composite-encoderlayout), then the fields written will\nvary by the providers you configure.\n\n\n\n### Standard Fields\n\nThese fields will appear in every AccessEvent unless otherwise noted.\nThe field names listed here are the default field names.\nThe field names can be customized (see [Customizing Standard Field Names](#customizing-standard-field-names)).\n\n| Field            | Description                                                                                                       |\n|------------------|-------------------------------------------------------------------------------------------------------------------|\n| `@timestamp`     | Time of the log event. (`yyyy-MM-dd'T'HH:mm:ss.SSSZZ`)  See [customizing timestamp](#customizing-timestamp).      |\n| `@version`       | Logstash format version (e.g. `1`)   See [customizing version](#customizing-version).                             |\n| `message`        | Message in the form `${remoteHost} - ${remoteUser} [${timestamp}] \"${requestUrl}\" ${statusCode} ${contentLength}` |\n| `method`         | HTTP method                                                                                                       |\n| `protocol`       | HTTP protocol                                                                                                     |\n| `status_code`    | HTTP status code                                                                                                  |\n| `requested_url`  | Request URL                                                                                                       |\n| `requested_uri`  | Request URI                                                                                                       |\n| `remote_host`    | Remote host                                                                                                       |\n| `remote_user`    | Remote user                                                                                                       |\n| `content_length` | Content length                                                                                                    |\n| `elapsed_time`   | Elapsed time in millis                                                                                            |\n\n### Header Fields\n\nRequest and response headers are not logged by default, but can be enabled by specifying a field name for them, like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashAccessEncoder\"\u003e\n    \u003cfieldNames\u003e\n        \u003crequestHeaders\u003erequest_headers\u003c/requestHeaders\u003e\n        \u003cresponseHeaders\u003eresponse_headers\u003c/responseHeaders\u003e\n    \u003c/fieldNames\u003e\n\u003c/encoder\u003e\n```\n\nSee [Customizing Standard Field Names](#customizing-standard-field-names)) for more details.\n\nTo write the header names in lowercase (so that header names that only differ by case are treated the same),\nset `lowerCaseFieldNames` to true, like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashAccessEncoder\"\u003e\n    \u003cfieldNames\u003e\n        \u003crequestHeaders\u003erequest_headers\u003c/requestHeaders\u003e\n        \u003cresponseHeaders\u003eresponse_headers\u003c/responseHeaders\u003e\n    \u003c/fieldNames\u003e\n    \u003clowerCaseHeaderNames\u003etrue\u003c/lowerCaseHeaderNames\u003e\n\u003c/encoder\u003e\n```\n\nHeaders can be filtered via configuring the `requestHeaderFilter` and/or the `responseHeaderFilter`\nwith a [`HeaderFilter`](/src/main/java/net/logstash/logback/composite/accessevent/HeaderFilter.java), such as the\n[`IncludeExcludeHeaderFilter`](/src/main/java/net/logstash/logback/composite/accessevent/IncludeExcludeHeaderFilter.java).\n\nThe `IncludeExcludeHeaderFilter` can be configured like this:\n \n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashAccessEncoder\"\u003e\n    \u003cfieldNames\u003e\n        \u003crequestHeaders\u003erequest_headers\u003c/requestHeaders\u003e\n    \u003c/fieldNames\u003e\n    \u003crequestHeaderFilter\u003e\n        \u003cinclude\u003eContent-Type\u003c/include\u003e\n    \u003c/requestHeaderFilter\u003e\n\u003c/encoder\u003e\n```\n\nCustom filters implementing [`HeaderFilter`](/src/main/java/net/logstash/logback/composite/accessevent/HeaderFilter.java)\ncan be used by specifying the filter class like this:\n\n```xml\n\u003crequestHeaderFilter class=\"your.package.YourFilterClass\"/\u003e\n```\n\n## Customizing Jackson\n\nLogstash-logback-encoder uses [Jackson](https://github.com/FasterXML/jackson) to encode log and access events.\n\nLogstash-logback-encoder provides sensible defaults for Jackson, but gives you full control over the Jackson configuration.\n\nFor example, you can:\n* specify the [data format](#data-format)\n* customize the [`TokenStreamFactoryBuilder`, `MapperBuilder`, and `JsonGenerator`](#customizing-tokenstreamfactory-objectmapper-and-jsongenerator)\n* register [jackson modules](#registering-jackson-modules)\n* configure [character escapes](#customizing-character-escapes) \n\n### Data Format\n\nJSON is used by default, but other data formats supported by Jackson can be used.\n* [text data formats](https://github.com/FasterXML/jackson-dataformats-text)\n* [binary data formats](https://github.com/FasterXML/jackson-dataformats-binary)\n\n\u003e [!IMPORTANT]\n\u003e When using non-JSON data formats, you must include the appropriate jackson dataformat library on the runtime classpath,\n\u003e typically via a maven/gradle dependency  (e.g. for Smile, include `jackson-dataformat-smile`).\n\nThe following data formats are directly supported:\n* `cbor`\n* `json` (the default)\n* `smile`\n* `yaml`\n\nTo use one these formats, specify the `\u003cdataFormat\u003e` like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n  \u003cdataFormat\u003esmile\u003c/dataFormat\u003e\n\u003c/encoder\u003e\n```\n\nOther data formats can be used by implementing\n[`net.logstash.logback.dataformat.DataFormatFactory`](src/main/java/net/logstash/logback/decorate/DataFormatFactory.java),\nand configuring it like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n  \u003cdataFormatFactory class=\"your.CustomDataFormatFactory\"/\u003e\n\u003c/encoder\u003e\n```\n\n\nThe following [decorators](#customizing-tokenstreamfactory-objectmapper-and-jsongenerator)\ncan be used to configure data-format-specific write features:\n* [`CborWriteFeatureDecorator`](src/main/java/net/logstash/logback/decorate/cbor/CborWriteFeatureDecorator.java)\n* [`JsonWriteFeatureDecorator`](src/main/java/net/logstash/logback/decorate/json/JsonWriteFeatureDecorator.java)\n* [`SmileWriteFeatureDecorator`](src/main/java/net/logstash/logback/decorate/smile/SmileWriteFeatureDecorator.java)\n* [`YamlWriteFeatureDecorator`](src/main/java/net/logstash/logback/decorate/yaml/YamlWriteFeatureDecorator.java)\n\nFor example:\n\n```xml\n\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cdataFormat\u003esmile\u003c/dataFormat\u003e\n    \u003cdecorator class=\"net.logstash.logback.decorate.smile.SmileWriteFeatureDecorator\"\u003e\n        \u003cdisable\u003eWRITE_HEADER\u003c/disable\u003e\n    \u003c/decorator\u003e\n\u003c/encoder\u003e\n``` \n\n### Customizing TokenStreamFactory, ObjectMapper, and JsonGenerator\n\nThe `ObjectMapper`, `TokenStreamFactory` and `JsonGenerator` used to write output can be customized by instances of\n* [`MapperBuilderDecorator`](/src/main/java/net/logstash/logback/decorate/MapperBuilderDecorator.java)\n* [`TokenStreamFactoryBuilderDecorator`](/src/main/java/net/logstash/logback/decorate/TokenStreamFactoryBuilderDecorator.java)\n* [`JsonGeneratorDecorator`](/src/main/java/net/logstash/logback/decorate/JsonGeneratorDecorator.java).\n\n\nFor example, you could enable pretty printing by using the\n[PrettyPrintingDecorator](/src/main/java/net/logstash/logback/decorate/PrettyPrintingDecorator.java)\n\nOr customize object mapping like this:\n\n```java\npublic class MixInDecorator\u003cM extends ObjectMapper, B extends MapperBuilder\u003cM, B\u003e\u003e implements MapperBuilderDecorator\u003cM, B\u003e  {\n\n    @Override\n    public B decorate(B mapperBuilder) {\n        return mapperBuilder.addMixIn(MyTarget.class, MyMixin.class);\n    }\n}\n```\nand then specify the decorators in the logback.xml file like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n  \u003cdecorator class=\"net.logstash.logback.decorate.PrettyPrintingDecorator\"/\u003e\n  \u003cdecorator class=\"your.package.MixInDecorator\"/\u003e\n\u003c/encoder\u003e\n```\n\nJackson features can be enabled/disabled by using the following feature decorators:\n\n| Jackson Feature Enum         | Feature Decorator                                                  |\n|------------------------------|--------------------------------------------------------------------|\n| `TokenStreamFactory.Feature` | `net.logstash.logback.decorate.TokenStreamFactoryFeatureDecorator` |\n| `MapperFeature`              | `net.logstash.logback.decorate.MapperFeatureDecorator`             |\n| `SerializationFeature`       | `net.logstash.logback.decorate.SerializationFeatureDecorator`      |\n| `StreamWriteFeature`         | `net.logstash.logback.decorate.StreamWriteFeatureDecorator`        |\n| `JsonNodeFeature`            | `net.logstash.logback.decorate.JsonNodeFeatureDecorator`           |\n| `EnumFeature`                | `net.logstash.logback.decorate.EnumFeatureDecorator`               |\n| `DateTimeFeature`            | `net.logstash.logback.decorate.DateTimeFeatureDecorator`           |\n| `JsonWriteFeature`           | `net.logstash.logback.decorate.json.JsonWriteFeatureDecorator`     |\n| `SmileWriteFeature`          | `net.logstash.logback.decorate.smile.SmileWriteFeatureDecorator`   |\n| `YAMLWriteFeature`           | `net.logstash.logback.decorate.yaml.YamlWriteFeatureDecorator`     |\n| `CBORWriteFeature`           | `net.logstash.logback.decorate.cbor.CborWriteFeatureDecorator`     |\n\n\nFor example:\n\n```xml\n\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cdecorator class=\"net.logstash.logback.decorate.TokenStreamFactoryFeatureDecorator\"\u003e\n        \u003cdisable\u003eINTERN_PROPERTY_NAMES\u003c/disable\u003e\n    \u003c/decorator\u003e\n    \u003cdecorator class=\"net.logstash.logback.decorate.json.JsonWriteFeatureDecorator\"\u003e\n        \u003cenable\u003eWRITE_NUMBERS_AS_STRINGS\u003c/enable\u003e\n    \u003c/decorator\u003e\n\u003c/encoder\u003e\n``` \n\nSee the [net.logstash.logback.decorate](/src/main/java/net/logstash/logback/decorate) package\nand sub-packages for other decorators.\n\nIf you prefer pretty printing for easier interactive viewing of (error) logs, you\nmay also prefer to write the stacktrace as an array of strings where each string\nis a stacktrace line:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cdecorator class=\"net.logstash.logback.decorate.PrettyPrintingDecorator\"\u003e\n\t\t\u003cindentArraysWithNewLine\u003etrue\u003c/indentArraysWithNewLine\u003e\n    \u003c/decorator\u003e\n\t\u003cwriteStackTraceAsArray\u003etrue\u003c/writeStackTraceAsArray\u003e\n\u003c/encoder\u003e\n```\n\n### Registering Jackson Modules\n\nBy default, Jackson modules are dynamically registered via\n`MapperBuilder.findAndAddModules()`.\n\nTherefore, you just need to add jackson modules (e.g. jackson-datatypes-collections) to the classpath,\nand they will be dynamically registered.\n\nTo disable automatic discovery, set `\u003cfindAndRegisterJacksonModules\u003efalse\u003c/findAndRegisterJacksonModules\u003e` on the encoder/layout.\n\nIf you have a module that Jackson is not able to dynamically discover,\nyou can register it manually via a [`MapperBuilderDecorator`](#customizing-tokenstreamfactory-objectmapper-and-jsongenerator).\n\n### Customizing Character Escapes\n\nBy default, when a string is written as a JSON string value, any character not allowed in a JSON string will be escaped.\nFor example, the newline character (ASCII 10) will be escaped as `\\n`.\n\nTo customize these escape sequences, use the `net.logstash.logback.decorate.json.CharacterEscapesDecorator`.\n\nFor example, if you want to use something other than `\\n` as the escape sequence for the newline character, you can do the following:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cdecorator class=\"net.logstash.logback.decorate.json.CharacterEscapesDecorator\"\u003e\n        \u003cescape\u003e\n            \u003ctargetCharacterCode\u003e10\u003c/targetCharacterCode\u003e\n            \u003cescapeSequence\u003e\\u2028\u003c/escapeSequence\u003e\n        \u003c/escape\u003e\n    \u003c/decorator\u003e\n\u003c/encoder\u003e\n```\n\nYou can also disable all the default escape sequences by specifying `\u003cincludeStandardAsciiEscapesForJSON\u003efalse\u003c/includeStandardAsciiEscapesForJSON\u003e` on the `CharacterEscapesJsonFactoryDecorator`.\nIf you do this, then you will need to register custom escapes for each character that is illegal in JSON string values.  Otherwise, invalid JSON could be written.\n\n## Masking\n\nThe [`MaskingJsonGeneratorDecorator`](src/main/java/net/logstash/logback/mask/MaskingJsonGeneratorDecorator.java)\ncan be used to mask sensitive values (e.g. personally identifiable information (PII) or financial data).\n\nData to be masked can be identified by [path](#identifying-field-values-to-mask-by-path)\nand/or by [value](#identifying-field-values-to-mask-by-value).\n\n### Identifying field values to mask by path\n\nPaths of fields to mask can be specified in several ways, as shown in the following example:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cdecorator class=\"net.logstash.logback.mask.MaskingJsonGeneratorDecorator\"\u003e\n    \n        \u003c!-- The default mask string can optionally be specified by \u003cdefaultMask\u003e.\n             When the default mask string is not specified, **** is used.\n        --\u003e\n        \u003cdefaultMask\u003e****\u003c/defaultMask\u003e\n        \n        \u003c!-- Field paths to mask added via \u003cpath\u003e will use the default mask string --\u003e\n        \u003cpath\u003esingleFieldName\u003c/path\u003e\n        \u003cpath\u003e/absolute/path/to/mask\u003c/path\u003e\n        \u003cpath\u003epartial/path/to/mask\u003c/path\u003e\n        \u003cpath\u003epartial/path/with/*/wildcard\u003c/path\u003e\n        \u003cpath\u003etilde~0slash~1escapedPath\u003c/path\u003e\n        \n        \u003c!-- Multiple field paths can be specified as a comma separated string in the \u003cpaths\u003e element. --\u003e\n        \u003cpaths\u003epath1, path2, path3\u003c/paths\u003e\n        \n        \u003c!-- Field paths to mask added via \u003cpathMask\u003e can use a non-default mask string --\u003e\n        \u003cpathMask\u003e\n            \u003cpath\u003esome/path\u003c/path\u003e\n            \u003cpath\u003esome/other/path\u003c/path\u003e\n            \u003cmask\u003e[masked]\u003c/mask\u003e\n        \u003c/pathMask\u003e\n        \u003cpathMask\u003e\n            \u003cpaths\u003eanotherFieldName,anotherFieldName2\u003c/paths\u003e\n            \u003cmask\u003e**anotherCustomMask**\u003c/mask\u003e\n        \u003c/pathMask\u003e\n        \n        \u003c!-- Field paths to mask can be supplied dynamically with an implementation\n             of MaskingJsonGeneratorDecorator.PathMaskSupplier\n        --\u003e\n        \u003cpathMaskSupplier class=\"your.custom.PathMaskSupplierA\"/\u003e\n        \n        \u003c!-- Custom implementations of net.logstash.logback.mask.FieldMasker\n             can be used for more advanced masking behavior\n        --\u003e\n        \u003cfieldMasker class=\"your.custom.FieldMaskerA\"/\u003e\n        \u003cfieldMasker class=\"your.custom.FieldMaskerB\"/\u003e\n    \u003c/decorator\u003e\n\u003c/encoder\u003e\n```\n\nSee [`PathBasedFieldMasker`](src/main/java/net/logstash/logback/mask/PathBasedFieldMasker.java)\nfor the path string format and more examples.  But in general:\n\n* Paths follow a format similar to (but not _exactly_ same as) a [JSON Pointer](http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-03).\n* Absolute paths start with `/` and are absolute to the root of the JSON output event (e.g. `/@timestamp` would mask the default timestamp field)\n* Partial paths do not start with `/` and match anywhere that path sequence is seen in the output.\n* A path with a single token (i.e. no `/` characters) will match all occurrences of a field with the given name\n* A wildcard token (`*`) will match anything at that location within the path\n* Use `~1` to escape `/` within a token\n* Use `~0` to escape `~` within a token\n\n### Identifying field values to mask by value\n\nSpecific values to be masked can be specified in several ways, as seen in the following example:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cdecorator class=\"net.logstash.logback.mask.MaskingJsonGeneratorDecorator\"\u003e\n    \n        \u003c!-- The default mask string can optionally be specified by \u003cdefaultMask\u003e.\n             When the default mask string is not specified, **** is used.\n        --\u003e\n        \u003cdefaultMask\u003e****\u003c/defaultMask\u003e\n        \n        \u003c!-- Values to mask added via \u003cvalue\u003e will use the default mask string --\u003e\n        \u003cvalue\u003e^foo$\u003c/value\u003e\n        \u003cvalue\u003ebar\u003c/value\u003e\n        \n        \u003c!-- Multiple values can be specified as a comma separated string in the \u003cvalues\u003e element. --\u003e\n        \u003cvalues\u003e\n            ^baz$,\n            ^blah$\n        \u003c/values\u003e\n        \n        \u003c!-- Values to mask added via \u003cvalueMask\u003e can use a non-default mask string\n             The mask string here can reference regex capturing groups if needed \n        --\u003e\n        \u003cvalueMask\u003e\n            \u003cvalue\u003e^(foo)-.*$\u003c/value\u003e\n            \u003cvalue\u003e^(bar)-.*$\u003c/value\u003e\n            \u003cmask\u003e$1****\u003c/mask\u003e\n        \u003c/valueMask\u003e\n        \n        \u003c!-- Values to mask can be supplied dynamically with an implementation of\n             MaskingJsonGeneratorDecorator.ValueMaskSupplier\n        --\u003e\n        \u003cvalueMaskSupplier class=\"your.custom.ValueMaskSupplierA\"/\u003e\n        \n        \u003c!-- Custom implementations of net.logstash.logback.mask.ValueMasker\n             can be used for more advanced masking behavior\n        --\u003e\n        \u003cvalueMasker class=\"your.custom.ValueMaskerA\"/\u003e\n        \u003cvalueMasker class=\"your.custom.ValueMaskerB\"/\u003e\n    \u003c/decorator\u003e\n\u003c/encoder\u003e\n```\n\nIdentifying data to mask by value is much more expensive than identifying data to mask by [path](#identifying-field-values-to-mask-by-path).\nTherefore, prefer identifying data to mask by path.\n\nThe value to mask is passed through every value masker, with the output of one masker passed as input to the next masker. \nThis allows each masker to mask specific substrings within the value.\nThe order in which the maskers are executed is not defined, and should not be relied upon.\n\nWhen using regexes to identify strings to mask, all matches within each string field value will be replaced.\nIf you want to match the full string field value, then use the beginning of line (`^`) and end of line (`$`) markers.\n\n\n## Customizing Standard Field Names\n\nThe standard field names above for LoggingEvents and AccessEvents can be customized by using the `fieldNames`configuration element in the encoder or appender configuration.\n\nFor example:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cfieldNames\u003e\n        \u003ctimestamp\u003etime\u003c/timestamp\u003e\n        \u003cmessage\u003emsg\u003c/message\u003e\n        \u003cstackTrace\u003estacktrace\u003c/stackTrace\u003e\n        ...\n    \u003c/fieldNames\u003e\n\u003c/encoder\u003e\n```\nPrevent a field from being output by setting the field name to `[ignore]`.\n\nFor LoggingEvents, see [`LogstashFieldNames`](/src/main/java/net/logstash/logback/fieldnames/LogstashFieldNames.java)\nfor all the field names that can be customized.  Each java field name in that class is the name of the xml element that you would use to specify the field name (e.g. `logger`, `levelValue`).  Additionally, a separate set of [shortened field names](/src/main/java/net/logstash/logback/fieldnames/ShortenedFieldNames.java) can be configured like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cfieldNames class=\"net.logstash.logback.fieldnames.ShortenedFieldNames\"/\u003e\n\u003c/encoder\u003e\n```\n\nFor LoggingEvents, log the caller info, MDC properties, and context properties\nin sub-objects within the JSON event by specifying field\nnames for `caller`, `mdc`, and `context`, respectively.\n\nFor AccessEvents, see [`LogstashAccessFieldNames`](/src/main/java/net/logstash/logback/fieldnames/LogstashAccessFieldNames.java)\nfor all the field names that can be customized. Each java field name in that class is the name of the xml element that you would use to specify the field name (e.g. `fieldsMethod`, `fieldsProtocol`).\n\n\n## Customizing Version\n\nThe version field value by default is the string value `1`.\n\nThe value can be changed like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cversion\u003e2\u003c/version\u003e\n\u003c/encoder\u003e\n```\n\nThe value can be written as a number (instead of a string) like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cwriteVersionAsInteger\u003etrue\u003c/writeVersionAsInteger\u003e\n\u003c/encoder\u003e\n```\n\n\n## Customizing Timestamp\n\nBy default, timestamps are written as string values in the format specified by\n[`DateTimeFormatter.ISO_OFFSET_DATE_TIME`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html#ISO_OFFSET_DATE_TIME)\n(e.g. `2019-11-03T10:15:30.123+01:00`), in the default TimeZone of the host Java platform.\n\nYou can change the pattern like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003ctimestampPattern\u003eyyyy-MM-dd'T'HH:mm:ss.SSS\u003c/timestampPattern\u003e\n\u003c/encoder\u003e\n```\n\nThe value of the `timestampPattern` can be any of the following:\n\n* `[UNIX_TIMESTAMP_AS_NUMBER]` - timestamp written as a JSON number value of the milliseconds since unix epoch\n* `[UNIX_TIMESTAMP_AS_STRING]` - timestamp written as a JSON string value of the milliseconds since unix epoch\n* `[` _`constant`_ `]` - (e.g. `[ISO_OFFSET_DATE_TIME]`) timestamp written using the given `DateTimeFormatter` constant\n* any other value - (e.g. `yyyy-MM-dd'T'HH:mm:ss.SSS`) timestamp written using a `DateTimeFormatter` created from the given pattern\n\nThe provider uses a standard Java DateTimeFormatter under the hood. However, special optimisations are applied when using one of the following standard ISO formats that make it nearly 7x faster and more GC friendly:\n\n* `[ISO_OFFSET_DATE_TIME]`\n* `[ISO_ZONED_DATE_TIME]`\n* `[ISO_LOCAL_DATE_TIME]`\n* `[ISO_DATE_TIME]`\n* `[ISO_INSTANT]`\n\n\nWith logback 1.3+ the timestamp will have millisecond precision.\n\nThe formatter uses the default TimeZone of the host Java platform by default. You can change it like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003ctimeZone\u003eUTC\u003c/timeZone\u003e\n\u003c/encoder\u003e\n```\n\nThe value of the `timeZone` element can be any string accepted by java's `TimeZone.getTimeZone(String id)` method.\nFor example `America/Los_Angeles`, `GMT+10` or `UTC`.\nUse the special value `[DEFAULT]` to use the default TimeZone of the system.\n\n\n\n## Customizing LoggingEvent Message\n\nBy default, LoggingEvent messages are written as JSON strings. Any characters not allowed in a JSON string, such as newlines, are escaped.\nSee the [Customizing Character Escapes](#customizing-character-escapes) section for details.\n\nYou can also write messages as JSON arrays instead of strings, by specifying a `messageSplitRegex` to split the message text.\nThis configuration element can take the following values:\n\n* any valid regex pattern\n* `SYSTEM` (uses the system-default line separator)\n* `UNIX` (uses `\\n`)\n* `WINDOWS` (uses `\\r\\n`)\n\nIf you split the log message by the origin system's line separator, the written message does not contain any embedded line separators.\nThe target system can unambiguously parse the message without any knowledge of the origin system's line separators.\n\nFor example:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cmessageSplitRegex\u003eSYSTEM\u003c/messageSplitRegex\u003e\n\u003c/encoder\u003e\n```\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cmessageSplitRegex\u003e\\r?\\n\u003c/messageSplitRegex\u003e\n\u003c/encoder\u003e\n```\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cmessageSplitRegex\u003e#+\u003c/messageSplitRegex\u003e\n\u003c/encoder\u003e\n```\n\n## Customizing AccessEvent Message\n\nBy default, AccessEvent messages are written in the following format:\n\n```\n%clientHost - %user [%date] \"%requestURL\" %statusCode %bytesSent\n```\n\nTo customize the message pattern, specify the `messagePattern` like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashAccessEncoder\"\u003e\n    \u003cmessagePattern\u003e%clientHost [%date] \"%requestURL\" %statusCode %bytesSent\u003c/messagePattern\u003e\n\u003c/encoder\u003e\n```\n\nThe pattern can contain any of the [AccessEvent conversion words](http://logback.qos.ch/manual/layouts.html#AccessPatternLayout).\n\n\n## Customizing Logger Name Length\n\nFor LoggingEvents, you can shorten the logger name field length similar to the normal pattern style of `%logger{36}`.\nExamples of how it is shortened can be found [here](https://logback.qos.ch/manual/layouts.html#logger).\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cshortenedLoggerNameLength\u003e36\u003c/shortenedLoggerNameLength\u003e\n\u003c/encoder\u003e\n```\n\nThe algorithm will shorten the logger name and attempt to reduce its size down to a maximum of number of characters.\nIt does so by reducing each part between dots to their first letter and gradually expand them starting from the right most element until the maximum size is reached.\n\nTo enable this feature, set the `shortenedLoggerNameLength` property to the desired value.\nSetting the length to zero constitutes an exception and returns only the part of the logger name after last dot.\nUse `-1` to disable shortening entirely.\n\nThe next table provides examples of the abbreviation algorithm in action.\n\n| LENGTH | LOGGER NAME                | SHORTENED                  |\n|--------|----------------------------|----------------------------|\n| 0      | `org.company.stack.Sample` | `Sample`                   |\n| 5      | `org.company.stack.Sample` | `o.c.s.Sample`             |\n| 16     | `org.company.stack.Sample` | `o.c.stack.Sample`         |\n| 22     | `org.company.stack.Sample` | `o.company.stack.Sample`   |\n| 25     | `org.company.stack.Sample` | `org.company.stack.Sample` |\n\n\n\n## Customizing Stack Traces\n\nWhen [logging exceptions](https://www.baeldung.com/slf4j-log-exceptions),\nstack traces are formatted using logback's `ExtendedThrowableProxyConverter` by default.\nHowever, you can configure the encoder to use any [`ThrowableHandlingConverter`](https://logback.qos.ch/apidocs/ch/qos/logback/classic/pattern/ThrowableHandlingConverter.html) to format stacktraces.\n\nNote that the `ThrowableHandlingConverter` only applies to the\n[exception passed as an extra argument](https://www.baeldung.com/slf4j-log-exceptions)\nto the log method, the way you normally log an exception in slf4j.\nDo **NOT** use [structured arguments or markers](#event-specific-custom-fields) for exceptions.\n\nA powerful [`ShortenedThrowableConverter`](/src/main/java/net/logstash/logback/stacktrace/ShortenedThrowableConverter.java) is included in the logstash-logback-encoder library to format stacktraces with the features listed in the next sections.\nThis converter can even be used within a `PatternLayout` to format stacktraces in any non-JSON logs you may have.\n\n\n### Omit Common Frames\n\nNested stacktraces often contain redundant frames that can safely be omitted without loosing any valuable information.\n\nThe following example shows a standard stack trace of an exception with a single root cause:\n\n```\njava.lang.RuntimeException: Unable to invoke service\n\tat org.company.stack.gen.StackGenerator.causedBy(StackGenerator.java:40)\n\tat org.company.stack.gen.StackGenerator.generateCausedBy(StackGenerator.java:34)\n\tat org.company.stack.framework.Dispatcher.invoke(Dispatcher.java:11)\n\tat org.company.stack.framework.Dispatcher.dispatch(Dispatcher.java:8)\n\tat org.company.stack.Sample.execute(Sample.java:36)\n\tat org.company.stack.Sample.omitCommonFrames(Sample.java:22)\n\tat org.company.stack.Sample.main(Sample.java:18)\nCaused by: java.lang.RuntimeException: Destination unreachable\n\tat org.company.stack.gen.StackGenerator.two(StackGenerator.java:58)\n\tat org.company.stack.gen.StackGenerator.one(StackGenerator.java:55)\n\tat org.company.stack.gen.StackGenerator.causedBy(StackGenerator.java:38)\n\tat org.company.stack.gen.StackGenerator.generateCausedBy(StackGenerator.java:34)\n\tat org.company.stack.framework.Dispatcher.invoke(Dispatcher.java:11)\n\tat org.company.stack.framework.Dispatcher.dispatch(Dispatcher.java:8)\n\tat org.company.stack.Sample.execute(Sample.java:36)\n\tat org.company.stack.Sample.omitCommonFrames(Sample.java:22)\n\tat org.company.stack.Sample.main(Sample.java:18)\n```\n\nAs we can see, the exception and the root cause have the first 7 frames in common. The overall stack trace length can be reduced by omitting these redundant frames from the root cause, as shown below:\n\n```\njava.lang.RuntimeException: Unable to invoke service\n\tat org.company.stack.gen.StackGenerator.causedBy(StackGenerator.java:40)\n\tat org.company.stack.gen.StackGenerator.generateCausedBy(StackGenerator.java:34)\n\tat org.company.stack.framework.Dispatcher.invoke(Dispatcher.java:11)\n\tat org.company.stack.framework.Dispatcher.dispatch(Dispatcher.java:8)\n\tat org.company.stack.Sample.execute(Sample.java:36)\n\tat org.company.stack.Sample.omitCommonFrames(Sample.java:22)\n\tat org.company.stack.Sample.main(Sample.java:18)\nCaused by: java.lang.RuntimeException: Destination unreachable\n\tat org.company.stack.gen.StackGenerator.two(StackGenerator.java:58)\n\tat org.company.stack.gen.StackGenerator.one(StackGenerator.java:55)\n\tat org.company.stack.gen.StackGenerator.causedBy(StackGenerator.java:38)\n\t... 6 common frames omitted\n```\n\nCommon frames are omitted and replaced with a message indicating the number of frames dropped. Note that the last common frame remains as a visual cue to the reader.\n\nThis feature is enabled by default and can be disabled if desired by setting the `omitCommonFrames` property to `false`.\n\n\n\n### Truncate after Regex\n\nIt is possible to use regular expressions to truncate the stacktrace after the first matching stacktrace element. The strings being matched against are in the form \"fullyQualifiedClassName.methodName\".\n\nFor example, to suppress everything below `org.company.stack.framework` package or after a call to the `StackGenerator.one()` method, configure the following:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cthrowableConverter class=\"net.logstash.logback.stacktrace.ShortenedThrowableConverter\"\u003e\n        \u003ctruncateAfter\u003e^org\\.company\\.stack\\.framework\\..*\u003c/truncateAfter\u003e\n        \u003ctruncateAfter\u003e^\\.StackGenerator\\.one\u003c/truncateAfter\u003e\n    \u003c/throwableConverter\u003e\n\u003c/encoder\u003e\n```\n\nThis will produce something similar to the following:\n\n```\njava.lang.RuntimeException: Unable to invoke service\n\tat org.company.stack.gen.StackGenerator.causedBy(StackGenerator.java:40)\n\tat org.company.stack.gen.StackGenerator.generateCausedBy(StackGenerator.java:34)\n\tat org.company.stack.framework.Dispatcher.invoke(Dispatcher.java:11)\n\t... 4 frames truncated\nCaused by: java.lang.RuntimeException: Destination unreachable\n\tat org.company.stack.gen.StackGenerator.two(StackGenerator.java:58)\n\tat org.company.stack.gen.StackGenerator.one(StackGenerator.java:55)\n\t... 7 frames truncated (including 6 common frames)\n```\n\nNote how the stacktrace is truncated _after_ the matching frames.\n\nAlternatively, multiple regex patterns can be specified at once using the `\u003ctruncateAfters\u003e` configuration keyword. This property accepts an optional comma separated list of patterns. The previous example configuration can also be written as follows:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cthrowableConverter class=\"net.logstash.logback.stacktrace.ShortenedThrowableConverter\"\u003e\n        \u003ctruncateAfters\u003e\n            ^org\\.company\\.stack\\.framework\\..*,\n            ^\\.StackGenerator\\.one\n        \u003c/truncateAfters\u003e\n    \u003c/throwableConverter\u003e\n\u003c/encoder\u003e\n```\n\nUsing the `\u003ctruncateAfters\u003e` configuration option can be useful when using an environment variable to specify the actual patterns at deployment time.\n\n\n\n### Exclude Frames per Regex\n\nSometimes portions of the stacktrace are not worthy of interest and you want to exclude them to make the overall stacktrace shorter. The encoder allows to filter out consecutive unwanted stacktrace elements based on regular expressions and replace them with a single message indicating \"something\" has been removed.\n\nTo enable this feature, simply define the regex patterns matching the frames you want to exclude using one or more `\u003cexclude\u003e` configuration keywords.\n\nTake the following stacktrace as an example:\n\n```\njava.lang.RuntimeException: Destination unreachable\n\tat org.company.stack.gen.StackGenerator.two(StackGenerator.java:58)\n\tat org.company.stack.gen.StackGenerator.one(StackGenerator.java:55)\n\tat org.company.stack.gen.StackGenerator.threeSingle$SpringCGLIB(StackGenerator.java:14)\n\tat org.company.stack.gen.StackGenerator.twoSingle$SpringCGLIB(StackGenerator.java:11)\n\tat org.company.stack.gen.StackGenerator.oneSingle$SpringCGLIB(StackGenerator.java:8)\n\tat org.company.stack.gen.StackGenerator.generateSingle(StackGenerator.java:5)\n\tat org.company.stack.framework.Dispatcher.invoke(Dispatcher.java:11)\n\tat org.company.stack.framework.Dispatcher.dispatch(Dispatcher.java:8)\n\tat org.company.stack.Sample.execute(Sample.java:107)\n\tat org.company.stack.Sample.exclude(Sample.java:94)\n\tat org.company.stack.Sample.main(Sample.java:19)\n```\n\nSuppose the last three frames are common to all your exceptions (they come from the application bootstrap) and you want to reduce them to a single line for brevetiy. Also, you are not interested in frames with `package.classname` ending with `$SpringCGLIB` because they are generated by the Spring runtime... To do this, you will use the following configuration:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cthrowableConverter class=\"net.logstash.logback.stacktrace.ShortenedThrowableConverter\"\u003e\n        \u003cexclude\u003e\\$SpringCGLIB$\u003c/exclude\u003e\n        \u003cexclude\u003e^org\\.company\\.stack\\.Sample\\..*\u003c/exclude\u003e\n    \u003c/throwableConverter\u003e\n\u003c/encoder\u003e\n```\n\nAnd your stacktrace would be rendered as follows:\n\n```\njava.lang.RuntimeException: Destination unreachable\n\tat org.company.stack.gen.StackGenerator.two(StackGenerator.java:58)\n\tat org.company.stack.gen.StackGenerator.one(StackGenerator.java:55)\n\t... 3 frames excluded\n\tat org.company.stack.gen.StackGenerator.generateSingle(StackGenerator.java:5)\n\tat org.company.stack.framework.Dispatcher.invoke(Dispatcher.java:11)\n\tat org.company.stack.framework.Dispatcher.dispatch(Dispatcher.java:8)\n\t... 3 frames excluded\n```\n\nNote that the converter effectively removes stack trace elements only if at least **TWO** consecutive frames match the configured regex patterns. This is to avoid replacing a single frame with \"... 1 frames excluded\" that doesn't shorten the stacktrace at all...\n\nIn addition, the first frame of the stacktrace is always output and cannot be excluded.\n\n\nAlternatively, multiple exclusion patterns can be specified at once using the `\u003cexclusions\u003e` configuration keyword. This property accepts an optional comma separated list of patterns. The previous example configuration can also be written as follows:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cthrowableConverter class=\"net.logstash.logback.stacktrace.ShortenedThrowableConverter\"\u003e\n        \u003cexclusions\u003e\n            \\$SpringCGLIB$,\n            ^org\\.company\\.stack\\.Sample\\..*\n        \u003c/exclusions\u003e\n    \u003c/throwableConverter\u003e\n\u003c/encoder\u003e\n```\n\nUsing the `\u003cexclusions\u003e` configuration option can be useful when using an environment variable to specify the actual patterns at deployment time.\n\n\n### Omit Throwable Messages\n\nTo omit throwable messages from stacktraces, add the `ShortenedThrowableConverter.OMIT_THROWABLE_MESSAGE` marker\nto log statements.\n\nConsider the following stacktrace (without omitting messages):\n\n```\nException in thread \"main\" com.myproject.module.MyProjectFooBarException: Customer ssn of 12345678 was not registered\n    at com.myproject.module.MyProject.anotherMethod(MyProject.java:19)\n    at com.myproject.module.MyProject.someMethod(MyProject.java:12)\n    at com.myproject.module.MyProject.main(MyProject.java:8)\nCaused by: java.lang.ArithmeticException: Could not generate userId for Customer with phone number 111-111-1111\n    at org.apache.commons.lang3.math.Fraction.getFraction(Fraction.java:143)\n    at com.myproject.module.MyProject.anotherMethod(MyProject.java:17)\n    ... 2 more\n```\n\nIf the `ShortenedThrowableConverter.OMIT_THROWABLE_MESSAGE` marker is used when logging the above throwable,\nthen the `ShortenedThrowableConverter` will omit all messages in the stacktrace.\n\nFor example, the following code:\n\n```java\n    logger.error(OMIT_THROWABLE_MESSAGE, \"An exception was thrown but I want to make sure no customer data is shown in stacktrace\", e);\n```\n\nwill produce:\n\n```\nException in thread \"main\" com.myproject.module.MyProjectFooBarException:\n    at com.myproject.module.MyProject.anotherMethod(MyProject.java:19)\n    at com.myproject.module.MyProject.someMethod(MyProject.java:12)\n    at com.myproject.module.MyProject.main(MyProject.java:8)\nCaused by: java.lang.ArithmeticException: \n    at org.apache.commons.lang3.math.Fraction.getFraction(Fraction.java:143)\n    at com.myproject.module.MyProject.anotherMethod(MyProject.java:17)\n    ... 2 more\n```\n\nThis enables devs to still see the type of exception thrown and where it occurred, **without** exposing sensitive data.\n\n### Maximum Depth per Throwable\n\nThe `maxDepthPerThrowable` property is used to limit the depth of each individual throwable nested inside the original exception, caused-bys and suppressed exceptions included. Beyond this limit, additional elements are omitted and a message indicating the number elements removed is added instead.\n\nFor example, the following configuration limits the stacktrace to 2 elements:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cthrowableConverter class=\"net.logstash.logback.stacktrace.ShortenedThrowableConverter\"\u003e\n        \u003cmaxDepthPerThrowable\u003e2\u003c/maxDepthPerThrowable\u003e\n    \u003c/throwableConverter\u003e\n\u003c/encoder\u003e\n```\n\nThis would produce something similar to the following:\n\n```\njava.lang.RuntimeException: Unable to invoke service\n\tat org.company.stack.gen.StackGenerator.causedBy(StackGenerator.java:40)\n\tat org.company.stack.gen.StackGenerator.generateCausedBy(StackGenerator.java:34)\n\t... 5 frames truncated\nCaused by: java.lang.RuntimeException: Destination unreachable\n\tat org.company.stack.gen.StackGenerator.two(StackGenerator.java:58)\n\tat org.company.stack.gen.StackGenerator.one(StackGenerator.java:55)\n\t... 7 frames truncated (including 6 common frames)\n```\n\nNote how the maximum depth applies to each individual throwables. The last message indicates that 7 frames were truncated of which 6 are common to both the exception and the cause.\n\nThe special value `-1` can be used to disable the feature and allow for an unlimited depth (no limit), which is the default.\n\n\n\n### Maximum Trace Size (bytes)\n\nThe `maxLength` property is used to set a limit on the size of the overall trace, all throwables combined.\n\nFor example, use the following configuration to limit the size to `256` characters:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cthrowableConverter class=\"net.logstash.logback.stacktrace.ShortenedThrowableConverter\"\u003e\n        \u003cmaxLength\u003e256\u003c/maxLength\u003e\n    \u003c/throwableConverter\u003e\n\u003c/encoder\u003e\n```\n\nThe overall trace will be limited to 256 characters like this:\n\n```\njava.lang.RuntimeException: Unable to invoke service\n\tat org.company.stack.gen.StackGenerator.causedBy(StackGenerator.java:40)\n\tat org.company.stack.gen.StackGenerator.generateCausedBy(StackGenerator.java:34)\n\tat org.company.stack.framework.Dispatcher....\n```\n\nThe special value `-1` can be used to disable the feature and allow for an unlimited length (no limit), which is the default.\n\n\n\n### Classname Shortening\n\nClass names can be abbreviated in a way similar to the Logback layout [feature](https://logback.qos.ch/manual/layouts.html#logger).\nThe algorithm will shorten the full class name (package + class) and attempt to reduce its size down to a maximum of number of characters.\nIt does so by reducing the package elements to their first letter and gradually expand them starting from the right most element until the maximum size is reached.\n\nTo enable this feature, set the `shortenedClassNameLength` property to the desired value.\nSetting the length to zero constitutes an exception and returns the \"simple\" class name without package name.\nSet length to `-1` to disable shortening entirely.\n\nThe next table provides examples of the abbreviation algorithm in action.\n\n|LENGTH|CLASSNAME                   |SHORTENED                  |\n|------|----------------------------|---------------------------|\n|0     | `org.company.stack.Sample` | `Sample`                  |\n|5     | `org.company.stack.Sample` | `o.c.s.Sample`            |\n|16    | `org.company.stack.Sample` | `o.c.stack.Sample`        |\n|22    | `org.company.stack.Sample` | `o.company.stack.Sample`  |\n|25    | `org.company.stack.Sample` | `org.company.stack.Sample`|\n\n\nFor example, use the following configuration to try to shorten the class names down to 25 characters:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cthrowableConverter class=\"net.logstash.logback.stacktrace.ShortenedThrowableConverter\"\u003e\n        \u003cshortenedClassNameLength\u003e25\u003c/shortenedClassNameLength\u003e\n    \u003c/throwableConverter\u003e\n\u003c/encoder\u003e\n```\n\nThis will produce an output similar to this:\n\n```\nj.lang.RuntimeException: Unable to invoke service\n\tat o.c.s.gen.StackGenerator.causedBy(StackGenerator.java:40)\n\tat o.c.s.gen.StackGenerator.generateCausedBy(StackGenerator.java:34)\n\tat o.c.s.f.Dispatcher.invoke(Dispatcher.java:11)\n\tat o.c.s.f.Dispatcher.dispatch(Dispatcher.java:8)\n\tat org.company.stack.Sample.execute(Sample.java:97)\n\tat org.company.stack.Sample.classNameShortening(Sample.java:77)\n\tat org.company.stack.Sample.main(Sample.java:19)\nCaused by: j.lang.RuntimeException: Destination unreachable\n\tat o.c.s.gen.StackGenerator.two(StackGenerator.java:58)\n\tat o.c.s.gen.StackGenerator.one(StackGenerator.java:55)\n\tat o.c.s.gen.StackGenerator.causedBy(StackGenerator.java:38)\n\t... 6 common frames omitted\n```\n\nNote that the exception name is also shortened, as are the individual frames.\n\nAlternatively you can specify your own custom abbreviation strategy with the `\u003cclassNameAbbreviator\u003e` configuration property as shown below:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cthrowableConverter\u003e\n        \u003cclassNameAbbreviator class=\"your.own.CustomAbbreviator\"\u003e\n            \u003cparam1\u003eaValue\u003c/param1\u003e\n        \u003c/classNameAbbreviator\u003e\n    \u003c/throwableConverter\u003e\n\u003c/encoder\u003e\n```\n\n\u003e **Note**\n\u003e The value of `\u003cshortenedClassNameLength\u003e` property is ignored when a custom abbreviator is explicitly specified.\n\n\n\n### Custom Line Separator\n\nStacktrace elements are sperated by the `SYSTEM` line separator by default. \nThe `linesSeparator` property can be used to specify a different value. The line separator can be specified as:\n\n* `SYSTEM` (uses the system default)\n* `UNIX` (uses `\\n`)\n* `WINDOWS` (uses `\\r\\n`), or\n* any other string.\n\nFor example, to use a pipe (`|`) as separator between stacktrace elements you would use the following configuration:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cthrowableConverter class=\"net.logstash.logback.stacktrace.ShortenedThrowableConverter\"\u003e\n        \u003clineSeparator\u003e|\u003c/lineSeparator\u003e\n    \u003c/throwableConverter\u003e\n\u003c/encoder\u003e\n```\n\nThe stacktrace will be rendered on a single line with `|` between frames as follows (the line is truncated for readability):\n\n```\njava.lang.RuntimeException: Unable to invoke service|\tat org.company.stack.gen.StackGenerator.causedBy(StackGenerator.java:40)|\tat org.c\n```\n\n\n### Root Cause First\n\nStacktraces are usually rendered with the root cause appearing last.\nYou can invert the order and have the root cause output first by setting the `rootCauseFirst` property to `true` (`false` by default).\n\nSample output:\n\n```\njava.lang.RuntimeException: Destination unreachable\n\tat org.company.stack.gen.StackGenerator.two(StackGenerator.java:58)\n\tat org.company.stack.gen.StackGenerator.one(StackGenerator.java:55)\n\tat org.company.stack.gen.StackGenerator.causedBy(StackGenerator.java:38)\n\t... 6 common frames omitted\nWrapped by: java.lang.RuntimeException: Unable to invoke service\n\tat org.company.stack.gen.StackGenerator.causedBy(StackGenerator.java:40)\n\tat org.company.stack.gen.StackGenerator.generateCausedBy(StackGenerator.java:34)\n\tat org.company.stack.framework.Dispatcher.invoke(Dispatcher.java:11)\n\tat org.company.stack.framework.Dispatcher.dispatch(Dispatcher.java:8)\n\tat org.company.stack.Sample.execute(Sample.java:79)\n\tat org.company.stack.Sample.rootCauseFirst(Sample.java:66)\n\tat org.company.stack.Sample.main(Sample.java:18)\n```\n\n\n### Conditional Output\n\nStandard Logback [EventEvaluators](https://logback.qos.ch/manual/filters.html#evalutatorFilter) can be used to determine if the stacktrace should be rendered.\n\nEventEvaluators are used to _skip_ generation of the stack trace for matching ILoggingEvents. In other words, an evaluator must evaluate to `false` (do not skip) to include the stacktrace...\n\nThe following sample configuration leverage the Logback [JaninoEventEvaluator](https://logback.qos.ch/manual/filters.html#JaninoEventEvaluator) event evaluator to output the stacktrace only if the log message contains the word `billing`:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003cthrowableConverter class=\"net.logstash.logback.stacktrace.ShortenedThrowableConverter\"\u003e\n        \u003cevaluator class=\"ch.qos.logback.classic.boolex.JaninoEventEvaluator\"\u003e\n            \u003cexpression\u003ereturn !message.contains(\"billing\");\u003c/expression\u003e\n        \u003c/evaluator\u003e\n    \u003c/throwableConverter\u003e\n\u003c/encoder\u003e\n```\n\nMultiple evaluators can be registered and are evaluated in the order in which they are registered. The stacktrace is only generated if all evaluators returned `false`.\n\n\n\n### Stack Hashes\n\nCompute and inline hexadecimal hashes for each exception stack with the `inlineHash` or `stackHash` provider ([more info](stack-hash.md)).\n\n\n\n### Using with PatternLayout\n\nTo use this with a PatternLayout, you must configure a new \"conversionRule\" as described [here](http://logback.qos.ch/manual/layouts.html#customConversionSpecifier). \n\nFor example:\n\n```xml\n\u003c!-- Define a new conversion rule named \"stack\" --\u003e\n\u003cconversionRule conversionWord=\"stack\"\n                converterClass=\"net.logstash.logback.stacktrace.ShortenedThrowableConverter\" /\u003e\n```\n\nThis configuration registers the `ShortenedThrowableConverter` under the name `stack`. From there the converter can be used in a PatternLayout using the syntax `%stack{options}` with optional configuration options between `{}`, each separated by a comma.\n\nThe first three options must appear in the following order:\n\n1. maxDepthPerThrowable - `full` or `short` or an integer value\n2. shortenedClassNameLength - `full` or `short` or an integer value\n3. maxLength - `full` or `short` or an integer value\n\nThe remaining options can appear in any order and are interpreted as follows:\n\n- keyword `rootFirst` - indicating that stacks should be printed root-cause first\n- keyword `inlineHash` - indicating that hexadecimal error hashes should be computed and inlined\n- keyword `inline` - indicating that the whole stack trace should be inlined, using `\\\\n` as separator\n- keyword `omitCommonFrames` - indicating that common frames should be omitted\n- keyword `keepCommonFrames` - indicating that common frames should be preserved\n- any other string:\n\t- first evaluated as the name of a registered Evaluator that will determine if the stacktrace is ignored,\n\t- if no evaluator is found with that name, the string is interpreted as a regex pattern for stack trace elements to exclude\n\nFor example,\n\n```xml\n\u003cappender name=\"STDOUT\" class=\"ch.qos.logback.core.ConsoleAppender\"\u003e\n    \u003cencoder\u003e\n        \u003cpattern\u003e[%thread] - %msg%n%stack{5,1024,10,rootFirst,omitCommonFrames,regex1,regex2,evaluatorName}\u003c/pattern\u003e\n    \u003c/encoder\u003e\n\u003c/appender\u003e\n```\n\nNote that it is not possible to configure the `truncateAfter` feature when the converter is used within a pattern layout.\n\n\n\n## Registering Additional Providers\n\n`LogstashEncoder`, `LogstashAccessEncoder` and their \"layout\" counterparts all come with a predefined set of encoders. You can register additional JsonProviders using the `\u003cprovider\u003e` configuration property as shown in the following example:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    \u003c!-- Add a new provider after those than come with the LogstashEncoder --\u003e\n    \u003cprovider class=\"net.logstash.logback.composite.loggingevent.LoggingEventPatternJsonProvider\"\u003e\n        \u003cpattern\u003e\n          {\n             \"message\": \"%mdc{custom_value} %message\"\n          }\n        \u003c/pattern\u003e\n    \u003c/provider\u003e\n\n    \u003c!-- Disable the default message provider --\u003e\n    \u003cfieldNames\u003e\n        \u003cmessage\u003e[ignore]\u003c/message\u003e\n    \u003c/fieldNames\u003e\n\u003c/encoder\u003e\n```\n\nYou can add several additional JsonProviders using multiple `\u003cprovider\u003e` entries. They will appear just after the default providers registered by the LogstashEncoder.\n\nIn this example, the pattern provider produces a \"message\" JSON field that will conflict with the message field produced by the MessageJsonProvider already registered by the LogstashEncoder itself. Different options to avoid the conflict:\n\n- you instruct LogstashEncoder to use a different field name using the [fieldNames](#customizing-standard-field-names) configuration property;\n- you disable the message provider that comes with the encoder (that's the option illustrated in the example above);\n- you use a different field name in your pattern.\n\n\n## Prefix/Suffix/Separator\n\nYou can specify a prefix (written before the JSON object),\nsuffix (written after the JSON object),\nand/or line separator (written after suffix),\nwhich may be required for the log pipeline you are using, such as:\n\n* If you are using the Common Event Expression (CEE) format for syslog, you need to add the `@cee:` prefix.\n* If you are using other syslog destinations, you might need to add the standard syslog headers.\n* If you are using Loggly, you might need to add your customer token.\n\nFor example, to add standard syslog headers for syslog over UDP, configure the following:\n\n```xml\n\u003cconfiguration\u003e\n    \u003cconversionRule conversionWord=\"syslogStart\" converterClass=\"ch.qos.logback.classic.pattern.SyslogStartConverter\"/\u003e\n\n    \u003cappender name=\"stash\" class=\"net.logstash.logback.appender.LogstashUdpSocketAppender\"\u003e\n        \u003chost\u003eMyAwesomeSyslogServer\u003c/host\u003e\n        \u003c!-- port is optional (default value shown) --\u003e\n        \u003cport\u003e514\u003c/port\u003e\n        \u003clayout\u003e\n            \u003cprefix class=\"ch.qos.logback.classic.PatternLayout\"\u003e\n                \u003cpattern\u003e%syslogStart{USER}\u003c/pattern\u003e\n            \u003c/prefix\u003e\n        \u003c/layout\u003e\n    \u003c/appender\u003e\n\n    ...\n\u003c/configuration\u003e\n```\n\nWhen using the `LogstashEncoder`, `LogstashAccessEncoder` or a composite encoder, the prefix is an `Encoder`, not a `Layout`, so you will need to wrap the prefix `PatternLayout` in a `LayoutWrappingEncoder` like this:\n\n```xml\n\u003cconfiguration\u003e\n    ...\n    \u003cappender ...\u003e\n        \u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n            ...\n            \u003cprefix class=\"ch.qos.logback.core.encoder.LayoutWrappingEncoder\"\u003e\n                \u003clayout class=\"ch.qos.logback.classic.PatternLayout\"\u003e\n                    \u003cpattern\u003e@cee:\u003c/pattern\u003e\n                \u003c/layout\u003e\n            \u003c/prefix\u003e    \n        \u003c/encoder\u003e\n    \u003c/appender\u003e\n\u003c/configuration\u003e\n```\n\nNote that logback's xml configuration reader will [trim whitespace from xml element values](https://github.com/qos-ch/logback/blob/c2dcbfcfb4048d11d7e81cd9220efbaaccf931fa/logback-core/src/main/java/ch/qos/logback/core/joran/event/BodyEvent.java#L27-L37).  Therefore, if you want to end the prefix or suffix pattern with whitespace, first add the whitespace, and then add something like `%mdc{keyThatDoesNotExist}` after it.  For example `\u003cpattern\u003eyour pattern %mdc{keyThatDoesNotExist}\u003c/pattern\u003e`.  This will cause logback to output the whitespace as desired, and then a blank string for the MDC key that does not exist.\n\nThe line separator, which is written after the suffix, can be specified as:\n* `SYSTEM` (uses the system default)\n* `UNIX` (uses `\\n`)\n* `WINDOWS` (uses `\\r\\n`), or\n* any other string.\n\nFor example:\n\n```xml\n\u003cconfiguration\u003e\n    ...\n    \u003cappender ...\u003e\n        \u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n            ...\n            \u003clineSeparator\u003eUNIX\u003c/lineSeparator\u003e\n        \u003c/encoder\u003e\n    \u003c/appender\u003e\n\u003c/configuration\u003e\n```\n\n## Composite Encoder/Layout\n\nIf you want greater flexibility in the JSON format and data included in LoggingEvents and AccessEvents, use the [`LoggingEventCompositeJsonEncoder`](/src/main/java/net/logstash/logback/encoder/LoggingEventCompositeJsonEncoder.java)  and  [`AccessEventCompositeJsonEncoder`](/src/main/java/net/logstash/logback/encoder/AccessEventCompositeJsonEncoder.java)  (or the corresponding layouts).\n\nThese encoders/layouts are composed of one or more JSON _providers_ that contribute to the JSON output.  No providers are configured by default in the composite encoders/layouts.  You must add the ones you want.\n\nFor example:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder\"\u003e\n    \u003cproviders\u003e\n        \u003cmdc/\u003e\n        \u003cpattern\u003e\n            \u003cpattern\u003e\n                {\n                  \"timestamp\": \"%date{ISO8601}\",\n                  \"myCustomField\": \"fieldValue\",\n                  \"relative\": \"#asLong{%relative}\"\n                }\n            \u003c/pattern\u003e\n        \u003c/pattern\u003e\n        \u003cstackTrace\u003e\n            \u003cthrowableConverter class=\"net.logstash.logback.stacktrace.ShortenedThrowableConverter\"\u003e\n                \u003cmaxDepthPerThrowable\u003e30\u003c/maxDepthPerThrowable\u003e\n                \u003cmaxLength\u003e2048\u003c/maxLength\u003e\n                \u003cshortenedClassNameLength\u003e20\u003c/shortenedClassNameLength\u003e\n                \u003cexclude\u003e^sun\\.reflect\\..*\\.invoke\u003c/exclude\u003e\n                \u003cexclude\u003e^net\\.sf\\.cglib\\.proxy\\.MethodProxy\\.invoke\u003c/exclude\u003e\n                \u003cevaluator class=\"myorg.MyCustomEvaluator\"/\u003e\n                \u003crootCauseFirst\u003etrue\u003c/rootCauseFirst\u003e\n            \u003c/throwableConverter\u003e\n        \u003c/stackTrace\u003e\n    \u003c/providers\u003e\n\u003c/encoder\u003e\n```\n\n\nThe logstash-logback-encoder library contains many providers out-of-the-box,\nand you can even plug-in your own by extending `JsonProvider`.\nEach provider has its own configuration options to further customize it.\n\nThese encoders/layouts make use of an internal buffer to hold the JSON output during the rendering process. \nThe size of this buffer is set to `1024` bytes by default. A different size can be configured by setting the `minBufferSize` property to the desired value.\nThe buffer automatically grows above the `minBufferSize` when needed to accommodate with larger events. However, only the first `minBufferSize` bytes will be reused by subsequent invocations. It is therefore strongly advised to set the minimum size at least equal to the average size of the encoded events to reduce unnecessary memory allocations and reduce pressure on the garbage collector.\n\n### Providers common to LoggingEvents and AccessEvents\n\nThe table below lists the providers available to both _LoggingEvents_ and _AccessEvents_.\nThe provider name is the xml element name to use when configuring.\n\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003cth\u003eProvider\u003c/th\u003e\n      \u003cth\u003eDescription/Properties\u003c/th\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003econtext\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eOutputs entries from logback's context.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Sub-object field name (no sub-object)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003enestedField\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003cp\u003eNests a JSON object under the configured fieldName.\u003c/p\u003e\n        \u003cp\u003eThe nested object is populated by other providers added to this provider.\u003c/p\u003e\n        \u003cp\u003eSee \u003ca href=\"#nested-json-provider\"\u003eNested JSON provider\u003c/a\u003e.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003eproviders\u003c/tt\u003e - The providers that should populate the nested object.\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003epattern\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003cp\u003eOutputs fields from a configured JSON Object string,\n           while substituting patterns supported by logback's \u003ctt\u003ePatternLayout\u003c/tt\u003e.\n        \u003c/p\u003e\n        \u003cp\u003e\n           See \u003ca href=\"#pattern-json-provider\"\u003ePattern JSON Provider\u003c/a\u003e\n        \u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003epattern\u003c/tt\u003e - JSON object string (no default)\u003c/li\u003e          \n          \u003cli\u003e\u003ctt\u003eomitEmptyFields\u003c/tt\u003e - whether to omit fields with empty values (\u003ctt\u003efalse\u003c/tt\u003e)\u003c/li\u003e          \n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003esequence\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003cp\u003eEvent sequence number.\n        \u003c/p\u003e\n        \u003cp\u003eWith Logback 1.3+ the sequence number is obtained from the event itself as long as the LoggerContext is configured with a `SequenceNumberGenerator` (which is not by default).\nIf no SequenceNumberGenerator is configured, the provider emits a warning and reverts to a locally generated incrementing number starting at 1.\n        \u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003esequence\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003esequenceProvider\u003c/tt\u003e - Alternate strategy to obtain the sequence number associated with the supplied event. Must implement `Function\u003cILoggingEvent, Long\u003e` or `Function\u003cIAccessEvent, Long\u003e` depending on the type of event to process.\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003ethreadName\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eName of the thread from which the event was logged.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003ethread_name\u003c/tt\u003e)\u003c/li\u003e          \n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003etimestamp\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eEvent timestamp.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003e@timestamp\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003epattern\u003c/tt\u003e - Output format (\u003ctt\u003e[ISO_OFFSET_DATE_TIME]\u003c/tt\u003e)  See \u003ca href=\"#customizing-timestamp\"\u003eCustomizing Timestamp\u003c/a\u003e for possible values.\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003etimeZone\u003c/tt\u003e - Timezone (system timezone)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003euuid\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003cp\u003e\n          Outputs random UUID as field value. Handy when you want to provide unique identifier\n          for log lines.\n        \u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003euuid\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003estrategy\u003c/tt\u003e - UUID generation strategy (\u003ctt\u003erandom\u003c/tt\u003e). Supported options: \u003cul\u003e\u003cli\u003e\u003ctt\u003erandom\u003c/tt\u003e - for Type 4 UUID\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003etime\u003c/tt\u003e - for Type 1 time based UUID\u003c/li\u003e\n          \u003c/ul\u003e\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003eethernet\u003c/tt\u003e - Only for 'time' strategy. When defined - MAC address to use for location part of UUID. Set it to \u003ctt\u003einterface\u003c/tt\u003e value to use real underlying network interface or to specific values like \u003ctt\u003e00:C0:F0:3D:5B:7C\u003c/tt\u003e\u003c/li\u003e          \n        \u003c/ul\u003e\n          \u003cp\u003eNote: The \u003ca href=\"https://mvnrepository.com/artifact/com.fasterxml.uuid/java-uuid-generator/\"\u003e\u003ctt\u003ecom.fasterxml.uuid:java-uuid-generator\u003c/tt\u003e\u003c/a\u003e optional dependency must be added to applications that use the `uuid` provider.\u003c/p\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003eversion\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eLogstash JSON format version.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003e@version\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003eversion\u003c/tt\u003e - Output value (\u003ctt\u003e1\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003ewriteAsInteger\u003c/tt\u003e - Write the version as a integer value (\u003ctt\u003efalse\u003c/tt\u003e = write as a string value)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\n### Providers for LoggingEvents\n\nThe [common providers mentioned above](#providers-common-to-loggingevents-and-accessevents), and the providers listed in the table below, are available for _LoggingEvents_.\nThe provider name is the xml element name to use when configuring. Each provider's configuration properties are shown, with default configuration values in parenthesis.\n\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003cth\u003eProvider\u003c/th\u003e\n      \u003cth\u003eDescription/Properties\u003c/th\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003earguments\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003cp\u003eOutputs fields from the event arguments array.\u003c/p\u003e\n        \u003cp\u003eSee \u003ca href=\"#event-specific-custom-fields\"\u003eEvent-specific Custom Fields\u003c/a\u003e.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Sub-object field name (no sub-object)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003eincludeNonStructuredArguments\u003c/tt\u003e - Include arguments that are not an instance\n          of \u003ca href=\"/src/main/java/net/logstash/logback/argument/StructuredArgument.java\"\u003e\u003ctt\u003eStructuredArgument\u003c/tt\u003e\u003c/a\u003e. \n          Object field name will be \u003ctt\u003enonStructuredArgumentsFieldPrefix\u003c/tt\u003e prepend to the argument index.\n          (default=false)\n          \u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003enonStructuredArgumentsFieldPrefix\u003c/tt\u003e - Object field name prefix (default=arg)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e \n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003ecallerData\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eOutputs data about from where the logger was called (class/method/file/line).\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Sub-object field name (no sub-object)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003eclassFieldName\u003c/tt\u003e - Field name for class name (\u003ctt\u003ecaller_class_name\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003emethodFieldName\u003c/tt\u003e - Field name for method name (\u003ctt\u003ecaller_method_name\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003efileFieldName\u003c/tt\u003e - Field name for file name (\u003ctt\u003ecaller_file_name\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003elineFieldName\u003c/tt\u003e - Field name for line number (\u003ctt\u003ecaller_line_number\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003econtextName\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eOutputs the name of logback's context.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003econtext\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003eloggerName\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eName of the logger that logged the message.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003elogger_name\u003c/tt\u003e)\u003c/li\u003e          \n          \u003cli\u003e\u003ctt\u003eshortenedLoggerNameLength\u003c/tt\u003e - Length to which the name will be attempted to be abbreviated (no abbreviation)\u003c/li\u003e          \n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003elogLevel\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eLogger level text (INFO, WARN, etc).\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003elevel\u003c/tt\u003e)\u003c/li\u003e          \n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003elogLevelValue\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eLogger level numerical value.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003elevel_value\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003elogstashMarkers\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eUsed to output Logstash Markers as specified in \u003cem\u003eEvent-specific Custom Fields\u003c/em\u003e.\u003c/p\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003emdc\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003cp\u003eOutputs entries from the Mapped Diagnostic Context (MDC).\n           Will include all entries by default.\n           When key names are specified for inclusion, then all other fields will be excluded.\n           When key names are specified for exclusion, then all other fields will be included.\n           It is a configuration error to specify both included and excluded key names.\n        \u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Sub-object field name (no sub-object)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003eincludeMdcKeyName\u003c/tt\u003e - Name of keys to include (all)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003eexcludeMdcKeyName\u003c/tt\u003e - Name of keys to exclude (none)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003emdcKeyFieldName\u003c/tt\u003e - Strings in the form \u003ctt\u003emdcKeyName=fieldName\u003c/tt\u003e\n              that specify an alternate field name to output for specific MDC key (none)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003ekeyValuePairs\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003cp\u003eOutputs key value pairs added via slf4j's fluent api.\n           Will include all key value pairs by default.\n           When key names are specified for inclusion, then all other keys will be excluded.\n           When key names are specified for exclusion, then all other keys will be included.\n           It is a configuration error to specify both included and excluded key names.\n        \u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Sub-object field name (no sub-object)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003eincludeKeyName\u003c/tt\u003e - Name of keys to include (all)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003eexcludeKeyName\u003c/tt\u003e - Name of keys to exclude (none)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003ekeyFieldName\u003c/tt\u003e - Strings in the form \u003ctt\u003ekeyName=fieldName\u003c/tt\u003e\n              that specify an alternate field name to output for specific key (none)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003emessage\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eFormatted log event message.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003emessage\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003emessageSplitRegex\u003c/tt\u003e - If null or empty, write the message text as is (the default behavior).\n              Otherwise, split the message text using the specified regex and write it as an array.\n              See the \u003ca href=\"#customizing-message\"\u003eCustomizing Message\u003c/a\u003e section for details.\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003erawMessage\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eRaw log event message, as opposed to formatted log where parameters are resolved.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003eraw_message\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003erootStackTraceElement\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003e(Only if a throwable was logged) Outputs a JSON Object containing the class and method name from which the outer-most exception was thrown.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003eroot_stack_trace_element\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003eclassFieldName\u003c/tt\u003e - Field name containing the class name from which the outermost exception was thrown (\u003ctt\u003eclass_name\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003emethodFieldName\u003c/tt\u003e - Field name containing the method name from which the outermost exception was thrown (\u003ctt\u003emethod_name\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003estackHash\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003e(Only if a throwable was logged) Computes and outputs a hexadecimal hash of the throwable stack.\u003c/p\u003e\n        \u003cp\u003eThis helps identifying several occurrences of the same error (\u003ca href=\"stack-hash.md\"\u003emore info\u003c/a\u003e).\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003estack_hash\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003eexclude\u003c/tt\u003e - Regular expression pattern matching \u003ci\u003estack trace elements\u003c/i\u003e to exclude when computing the error hash\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003eexclusions\u003c/tt\u003e - Comma separated list of regular expression patterns matching \u003ci\u003estack trace elements\u003c/i\u003e to exclude when computing the error hash\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003estackTrace\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eStacktrace of any throwable logged with the event. Stackframes are separated by newline chars.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003estack_trace\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003ethrowableConverter\u003c/tt\u003e - The \u003ctt\u003eThrowableHandlingConverter\u003c/tt\u003e to use to format the stacktrace (\u003ctt\u003estack_trace\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003ewriteAsArray\u003c/tt\u003e - write the stacktrace as an array of strings where each string is a stacktrace line\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003etags\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eOutputs logback markers as a comma separated list.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003etags\u003c/tt\u003e)\u003c/li\u003e          \n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003ethrowableClassName\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003e(Only if a throwable was logged) Outputs a field that contains the class name of the thrown Throwable.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003ethrowable_class\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003euseSimpleClassName\u003c/tt\u003e - When true, the throwable's simple class name will be used. When false, the fully qualified class name will be used. (\u003ctt\u003etrue\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003ethrowableMessage\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003e(Only if a throwable was logged) Outputs a field that contains the message of the thrown Throwable.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003ethrowable_message\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003ethrowableRootCauseClassName\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003e(Only if a throwable was logged and a root cause could be determined) Outputs a field that contains the class name of the root cause of the thrown Throwable.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003ethrowable_root_cause_class\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003euseSimpleClassName\u003c/tt\u003e - When true, the throwable's simple class name will be used. When false, the fully qualified class name will be used. (\u003ctt\u003etrue\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003ethrowableRootCauseMessage\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003e(Only if a throwable was logged and a root cause could be determined) Outputs a field that contains the message of the root cause of the thrown Throwable.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003ethrowable_root_cause_message\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\n\n### Providers for AccessEvents\n\nThe [common providers mentioned above](#providers-common-to-loggingevents-and-accessevents), and the providers listed in the table below, are available for _AccessEvents_.\nThe provider name is the xml element name to use when configuring. Each provider's configuration properties are shown, with default configuration values in parenthesis.\n\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003cth\u003eProvider\u003c/th\u003e\n      \u003cth\u003eDescription/Properties\u003c/th\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003econtentLength\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eContent length.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003econtent_length\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003eelapsedTime\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eElapsed time in milliseconds.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003eelapsed_time\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003emessage\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eMessage in the form `${remoteHost} - ${remoteUser} [${timestamp}] \"${requestUrl}\" ${statusCode} ${contentLength}`.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003emessage\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003epattern\u003c/tt\u003e - Output format of the timestamp (\u003ctt\u003e[ISO_OFFSET_DATE_TIME]\u003c/tt\u003e). See \u003ca href=\"#customizing-timestamp\"\u003eabove\u003c/a\u003e for possible values.\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003etimeZone\u003c/tt\u003e - Timezone (system timezone)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003emethod\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eHTTP method.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003emethod\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003eprotocol\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eHTTP protocol.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003eprotocol\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003eremoteHost\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eRemote Host.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003eremote_host\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003eremoteUser\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eRemote User.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003eremote_user\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003erequestedUri\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eRequested URI.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003erequested_uri\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003erequestedUrl\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eRequested URL.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003erequested_url\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003erequestHeaders\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eInclude the request headers.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (no default, must be provided)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003elowerCaseHeaderNames\u003c/tt\u003e - Write header names in lower case (\u003ctt\u003efalse\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003efilter\u003c/tt\u003e - A filter to determine which headers to include/exclude.\n          See \u003ca href=\"/src/main/java/net/logstash/logback/composite/accessevent/HeaderFilter.java\"\u003e\u003ctt\u003eHeaderFilter\u003c/tt\u003e\u003c/a\u003e\n          and \u003ca href=\"/src/main/java/net/logstash/logback/composite/accessevent/IncludeExcludeHeaderFilter.java\"\u003e\u003ctt\u003eIncludeExcludeHeaderFilter\u003c/tt\u003e\u003c/a\u003e\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003eresponseHeaders\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eInclude the response headers.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (no default, must be provided)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003elowerCaseHeaderNames\u003c/tt\u003e - Write header names in lower case (\u003ctt\u003efalse\u003c/tt\u003e)\u003c/li\u003e\n          \u003cli\u003e\u003ctt\u003efilter\u003c/tt\u003e - A filter to determine which headers to include/exclude.\n          See \u003ca href=\"/src/main/java/net/logstash/logback/composite/accessevent/HeaderFilter.java\"\u003e\u003ctt\u003eHeaderFilter\u003c/tt\u003e\u003c/a\u003e\n          and \u003ca href=\"/src/main/java/net/logstash/logback/composite/accessevent/IncludeExcludeHeaderFilter.java\"\u003e\u003ctt\u003eIncludeExcludeHeaderFilter\u003c/tt\u003e\u003c/a\u003e\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003ctt\u003estatusCode\u003c/tt\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003eHTTP status code.\u003c/p\u003e\n        \u003cul\u003e\n          \u003cli\u003e\u003ctt\u003efieldName\u003c/tt\u003e - Output field name (\u003ctt\u003estatus_code\u003c/tt\u003e)\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\n### Nested JSON Provider\n\nUse the `nestedField` provider to create a sub-object in the JSON event output.\n\nFor example...\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder\"\u003e\n    \u003cproviders\u003e\n        \u003ctimestamp/\u003e\n        \u003cnestedField\u003e\n            \u003cfieldName\u003efields\u003c/fieldName\u003e\n            \u003cproviders\u003e\n                \u003clogLevel/\u003e\n            \u003c/providers\u003e\n        \u003c/nestedField\u003e\n    \u003c/providers\u003e\n\u003c/encoder\u003e\n```\n\n...will produce something like...\n\n```json\n{\n    \"@timestamp\": \"...\",\n    \"fields\": {\n        \"level\": \"DEBUG\"\n    }\n}\n```\n\n\n### Pattern JSON Provider\n\nWhen used with a composite JSON encoder/layout, the `pattern` JSON provider can be used to\ndefine a template for a portion of the logged JSON output.\nThe encoder/layout will populate values within the template.\nEvery value in the template is treated as a pattern for logback's standard `PatternLayout` so it can be a combination\nof literal strings (for some constants) and various conversion specifiers (like `%d` for date).\n\nThe pattern string (configured within the pattern provider) must be a JSON Object.\nThe contents of the JSON object are included within the logged JSON output.\n\nThis example...\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder\"\u003e\n    \u003cproviders\u003e\n        \u003c!-- provides the timestamp --\u003e\n        \u003ctimestamp/\u003e\n\n        \u003c!-- provides the version --\u003e\n        \u003cversion/\u003e\n\n        \u003c!-- provides the fields in the configured pattern --\u003e\n        \u003cpattern\u003e\n            \u003c!-- the pattern that defines what to include --\u003e\n            \u003cpattern\u003e\n                { \"level\": \"%level\" }\n            \u003c/pattern\u003e\n        \u003c/pattern\u003e\n    \u003c/providers\u003e\n\u003c/encoder\u003e\n```\n... will produce something like...\n\n```\n{\n    \"@timestamp\": \"...\",\n    \"@version\": \"1\",\n    \"level\": \"DEBUG\"\n}\n```\n\nThe real power comes from the fact that there are lots of standard conversion specifiers so you\ncan customise what is logged and how. For example, you could log a single specific value from MDC with `%mdc{mykey}`.\nOr, for access logs, you could log a single request header with `%i{User-Agent}`.\n\nYou can use nested objects and arrays in your pattern.\n\nIf you use a null, number, or a boolean constant in a pattern, it will keep its type in the\nresulting JSON. However, only the text values are searched for conversion patterns.\nAnd, as these patterns are sent through `PatternLayout`, the result is always a string\neven for something which you may feel should be a number - like for `%b` (bytes sent, in access logs).\n\nYou can either deal with the type conversion on the logstash side or you may use special operations provided by this encoder.\nThe operations are:\n\n* `#asLong{...}` - evaluates the pattern in curly braces and then converts resulting string to a Long (or a `null` if conversion fails).\n* `#asDouble{...}` - evaluates the pattern in curly braces and then converts resulting string to a Double (or a `null` if conversion fails).\n* `#asBoolean{...}`- evaluates the pattern in curly braces and then converts resulting string to a Boolean. Conversion is case insensitive. `true`, `yes`, `y` and `1` (case insensitive) are converted to a boolean `true`, a `null` or empty string is converted to `null`, anything else returns `false`.\n* `asNullIfEmpty{...}` - evaluates the pattern in curly braces and the converts resulting string into `null` if it is empty.\n* `#asJson{...}` - evaluates the pattern in curly braces and then converts resulting string to json (or a `null` if conversion fails).\n* `#tryJson{...}` - evaluates the pattern in curly braces and then converts resulting string to json (or just the string if conversion fails).\n\nSo this example...\n\n```xml\n\u003cpattern\u003e\n    {\n        \"line_str\": \"%line\",\n        \"line_long\": \"#asLong{%line}\",\n        \"has_message\": \"#asBoolean{%mdc{hasMessage}}\",\n        \"json_message\": \"#asJson{%message}\"\n    }\n\u003c/pattern\u003e\n```\n\n... and this logging code...\n\n```java\nMDC.put(\"hasMessage\", \"true\");\nLOGGER.info(\"{\\\"type\\\":\\\"example\\\",\\\"msg\\\":\\\"example of json message with type\\\"}\");\n```\n\n...will produce something like...\n\n```json\n{\n    \"line_str\": \"97\",\n    \"line_long\": 97,\n    \"has_message\": true,\n    \"json_message\": {\"type\":\"example\",\"msg\":\"example of json message with type\"}\n}\n```\n\nNote that the value that is sent for `line_long` is a number even though in your pattern it is a quoted text.\nAnd the `json_message` field value is a json object, not a string.\n\nYou can escape an operation by prefixing it with `\\` if you don't want it to be interpreted.\n\n\n#### Omitting fields with empty values\n \nThe pattern provider can be configured to omit fields with the following _empty_ values:\n* `null`\n* empty string (`\"\"`)\n* empty array (`[]`)\n* empty object (`{}`)\n* objects containing only fields with empty values\n* arrays containing only empty values\n\nTo omit fields with empty values, configure `omitEmptyFields` to `true` (default is `false`), like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder\"\u003e\n    \u003cproviders\u003e\n        \u003cpattern\u003e\n            \u003comitEmptyFields\u003etrue\u003c/omitEmptyFields\u003e\n            \u003cpattern\u003e\n                {\n                    \"logger\": \"%logger\",\n                    \"level\": \"%level\",\n                    \"thread\": \"%thread\",\n                    \"message\": \"%message\",\n                    \"traceId\": \"%mdc{traceId}\"\n                }\n            \u003c/pattern\u003e\n        \u003c/pattern\u003e\n    \u003c/providers\u003e\n\u003c/encoder\u003e\n```\n\nIf the MDC did not contain a `traceId` entry, then a JSON log event from the above pattern would not contain the `traceId` field...\n\n```json\n{\n    \"logger\": \"com.example...\",\n    \"level\": \"DEBUG\",\n    \"thread\": \"exec-1\",\n    \"message\": \"Hello World!\"\n}\n```\n\n#### LoggingEvent patterns\n\nFor LoggingEvents, conversion specifiers from logback-classic's\n[`PatternLayout`](http://logback.qos.ch/manual/layouts.html#conversionWord) are supported.\n\nFor example:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder\"\u003e\n    \u003cproviders\u003e\n        \u003ctimestamp/\u003e\n        \u003cpattern\u003e\n            \u003cpattern\u003e\n                {\n                    \"custom_constant\": \"123\",\n                    \"tags\": [\"one\", \"two\"],\n                    \"logger\": \"%logger\",\n                    \"level\": \"%level\",\n                    \"thread\": \"%thread\",\n                    \"message\": \"%message\",\n                    ...\n                }\n            \u003c/pattern\u003e\n        \u003c/pattern\u003e\n    \u003c/providers\u003e\n\u003c/encoder\u003e\n```\n\nNote that the [`%property{key}`](https://logback.qos.ch/manual/layouts.html#property) conversion specifier behaves slightly differently when used in the context of the Pattern Json provider. If the property cannot be found in the logger context or the System properties, it returns **an empty string** instead of `null` as it would normally do. For example, assuming the \"foo\" property is not defined, `%property{foo}` would return `\"\"` (an empty string) instead of `\"null\"` (a string whose content is made of 4 letters).\n\nThe _property_ conversion specifier also allows you to specify a default value to use when the property is not defined. The default value is optional and can be specified using the `:-` operator as in Bash shell. For example, assuming the \"foo\" property is not defined, `%property{foo:-bar}` will return `bar`.\n\n\n#### AccessEvent patterns\n\nFor AccessEvents, conversion specifiers from logback-access's\n[`PatternLayout`](http://logback.qos.ch/xref/ch/qos/logback/access/PatternLayout.html) are supported.\n\nFor example:  \n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.AccessEventCompositeJsonEncoder\"\u003e\n    \u003cproviders\u003e\n        \u003cpattern\u003e\n            \u003cpattern\u003e\n                {\n                    \"custom_constant\": \"123\",\n                    \"tags\": [\"one\", \"two\"],\n                    \"remote_ip\": \"%a\",\n                    \"status_code\": \"%s\",\n                    \"elapsed_time\": \"%D\",\n                    \"user_agent\": \"%i{User-Agent}\",\n                    \"accept\": \"%i{Accept}\",\n                    \"referer\": \"%i{Referer}\",\n                    \"session\": \"%requestCookie{JSESSIONID}\",\n                    ...\n                }\n            \u003c/pattern\u003e\n        \u003c/pattern\u003e\n    \u003c/providers\u003e\n\u003c/encoder\u003e\n```\n\nThere is also a special operation that can be used with this AccessEvents:\n\n* `#nullNA{...}` - if the pattern in curly braces evaluates to a dash (`-`), it will be replaced with a `null` value.\n\nYou may want to use it because many of the `PatternLayout` conversion words from logback-access will evaluate to `-`\nfor non-existent value (for example for a cookie, header or a request attribute).\n\nSo the following pattern...\n\n```xml\n\u003cpattern\u003e\n    {\n        \"default_cookie\": \"%requestCookie{MISSING}\",\n        \"filtered_cookie\": \"#nullNA{%requestCookie{MISSING}}\"\n    }\n\u003c/pattern\u003e\n```\n\n...will produce...\n\n```json\n{\n    \"default_cookie\": \"-\",\n    \"filtered_cookie\": null\n}\n```\n\n### Custom JSON Provider\n\nYou can create your own JSON provider by implementing the [`JsonProvider`](src/main/java/net/logstash/logback/composite/JsonProvider.java) interface (or extending one of the existing classes that implements the `JsonProvider` interface).\n\nThen, add the provider to a `LoggingEventCompositeJsonEncoder` like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder\"\u003e\n    \u003cproviders\u003e\n        ...\n        \u003cprovider class=\"your.provider.YourJsonProvider\"\u003e\n            \u003c!-- Any properties exposed by your provider can be set here --\u003e\n        \u003c/provider\u003e\n        ...\n    \u003c/providers\u003e\n\u003c/encoder\u003e\n```\n\nor a `LogstashEncoder` like this:\n\n```xml\n\u003cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\"\u003e\n    ...\n    \u003cprovider class=\"your.provider.YourJsonProvider\"\u003e\n        \u003c!-- Any properties exposed by your provider can be set here --\u003e\n    \u003c/provider\u003e\n    ...\n\u003c/encoder\u003e\n```\n\nYou can do something similar for `AccessEventCompositeJsonEncoder` and `LogstashAccessEncoder` as well, if your `JsonProvider` handles `IAccessEvent`s.\n\n\n## Status Listeners\n\nDuring execution, the encoders/appenders/layouts provided in logstash-logback-encoder\nwill add logback status messages to the logback [`StatusManager`](https://logback.qos.ch/apidocs/ch/qos/logback/core/status/StatusManager.html).\nThese status messages are typically reported via a logback [`StatusListener`](https://logback.qos.ch/apidocs/ch/qos/logback/core/status/StatusListener.html).\n\nSince the [async appenders](#async-appenders) (especially the [tcp appenders](#tcp-appenders))\nreport warnings and errors via the status manager, a default status listener that\noutputs WARN and ERROR level status messages to standard out\nwill be registered on startup if a status listener has not already been registered.\nTo disable the automatic registering of the default status listener by an appender, do one of the following:\n* register a different logback [status listener](https://logback.qos.ch/manual/configuration.html#dumpingStatusData), or\n* set `\u003caddDefaultStatusListener\u003efalse\u003c/addDefaultStatusListener` in each async appender.\n\n\n## Joran/XML Configuration\n\nConfiguring Logback using XML is handled by Logback's Joran configuration system. This section is a short description of the high level data types supported by Joran. For more information, please refer to the [official documentation](http://logback.qos.ch/manual).\n\n### Duration property\n\nDuration represents a laps of time.\nIt can be specified as an integer value representing a number of milliseconds, or a string such as \"20 seconds\", \"3.5 minutes\" or \"5 hours\" that will be automatically  converted by logback's configuration system into Duration instances.\nThe recognized units of time are the `millisecond`, `second`, `minute`, `hour` and `day`. The unit name may be followed by an \"s\". Thus, \"2000 millisecond\" and \"2000 milliseconds\" are equivalent. In the absence of a time unit specification, milliseconds are assumed.\n\nThe following examples are therefore equivalent:\n\n```xml\n\u003cduration\u003e2000\u003c/duration\u003e\n\u003cduration\u003e2000 millisecond\u003c/duration\u003e\n\u003cduration\u003e2000 milliseconds\u003c/duration\u003e\n```\n\n### Comma separated list of values\n\nWhen specified, some properties accept a comma-separated list of values. \n\nLeading and trailing whistespace characters are removed from each value during the decoding process, including tabs (`\\t`), carriage return (`\\r`) and line feeds (`\\n`) - see the `String.trim()` function for more information. It is therefore safe to add an extra blank after the comma or write the values on multiple lines for better readability.\n\nThe examples below are equivalent and produce a list containing the values `valueA`, `valueB`, and `valueC`:\n\n```xml\n\u003cproperty\u003evalueA, valueB, valueC\u003c/property\u003e\n\n\u003cproperty\u003e\n    valueA,\n    valueB,\n    valueC\n\u003c/property\u003e\n```\n\nAlso, multiple consecutive comma are treated as a single delimiter. This allows you to write a generic configuration as follows where the actual value comes from an external environment variable whose value may be empty.\n\n```xml\n\u003cproperty\u003evalueA, ${ENV_VAR}, valueC\u003c/property\u003e\n```\n\nIf needed, the comma delimiter may be escaped by prefixing it with a backslash (`\\`) to treat it as being part of the value instead of considered as an actual delimiter. The example below defines a list containing one single element whose value is the string `foo,bar`:\n\n```xml\n\u003cproperty\u003efoo\\,bar\u003c/property\u003e\n```\n\n\n## Profiling\n\n\u003ca href=\"https://www.yourkit.com/java/profiler/\"\u003e\u003cimg src=\"https://www.yourkit.com/images/yk_logo.svg\" alt=\"YourKit Logo\" height=\"22\"/\u003e\u003c/a\u003e\n\nMemory usage and performance of logstash-logback-encoder have been improved\nby addressing issues discovered with the help of the\n[YourKit Java Profiler](https://www.yourkit.com/java/profiler/).\n\nYourKit, LLC has graciously donated a free license of the\n[YourKit Java Profiler](https://www.yourkit.com/java/profiler/)\nto this open source project.\n","funding_links":[],"categories":["Java","日志库"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flogfellow%2Flogstash-logback-encoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flogfellow%2Flogstash-logback-encoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flogfellow%2Flogstash-logback-encoder/lists"}