diff --git a/docs/docset.yml b/docs/docset.yml new file mode 100644 index 00000000..21c1c70f --- /dev/null +++ b/docs/docset.yml @@ -0,0 +1,489 @@ +project: 'ECS Logging Java' +cross_links: + - apm-agent-java + - beats + - ecs + - ecs-logging + - elasticsearch +toc: + - toc: reference +subs: + ref: "https://www.elastic.co/guide/en/elasticsearch/reference/current" + ref-bare: "https://www.elastic.co/guide/en/elasticsearch/reference" + ref-8x: "https://www.elastic.co/guide/en/elasticsearch/reference/8.1" + ref-80: "https://www.elastic.co/guide/en/elasticsearch/reference/8.0" + ref-7x: "https://www.elastic.co/guide/en/elasticsearch/reference/7.17" + ref-70: "https://www.elastic.co/guide/en/elasticsearch/reference/7.0" + ref-60: "https://www.elastic.co/guide/en/elasticsearch/reference/6.0" + ref-64: "https://www.elastic.co/guide/en/elasticsearch/reference/6.4" + xpack-ref: "https://www.elastic.co/guide/en/x-pack/6.2" + logstash-ref: "https://www.elastic.co/guide/en/logstash/current" + kibana-ref: "https://www.elastic.co/guide/en/kibana/current" + kibana-ref-all: "https://www.elastic.co/guide/en/kibana" + beats-ref-root: "https://www.elastic.co/guide/en/beats" + beats-ref: "https://www.elastic.co/guide/en/beats/libbeat/current" + beats-ref-60: "https://www.elastic.co/guide/en/beats/libbeat/6.0" + beats-ref-63: "https://www.elastic.co/guide/en/beats/libbeat/6.3" + beats-devguide: "https://www.elastic.co/guide/en/beats/devguide/current" + auditbeat-ref: "https://www.elastic.co/guide/en/beats/auditbeat/current" + packetbeat-ref: "https://www.elastic.co/guide/en/beats/packetbeat/current" + metricbeat-ref: "https://www.elastic.co/guide/en/beats/metricbeat/current" + filebeat-ref: "https://www.elastic.co/guide/en/beats/filebeat/current" + functionbeat-ref: "https://www.elastic.co/guide/en/beats/functionbeat/current" + winlogbeat-ref: "https://www.elastic.co/guide/en/beats/winlogbeat/current" + heartbeat-ref: "https://www.elastic.co/guide/en/beats/heartbeat/current" + journalbeat-ref: "https://www.elastic.co/guide/en/beats/journalbeat/current" + ingest-guide: "https://www.elastic.co/guide/en/ingest/current" + fleet-guide: "https://www.elastic.co/guide/en/fleet/current" + apm-guide-ref: "https://www.elastic.co/guide/en/apm/guide/current" + apm-guide-7x: "https://www.elastic.co/guide/en/apm/guide/7.17" + apm-app-ref: "https://www.elastic.co/guide/en/kibana/current" + apm-agents-ref: "https://www.elastic.co/guide/en/apm/agent" + apm-android-ref: "https://www.elastic.co/guide/en/apm/agent/android/current" + apm-py-ref: "https://www.elastic.co/guide/en/apm/agent/python/current" + apm-py-ref-3x: "https://www.elastic.co/guide/en/apm/agent/python/3.x" + apm-node-ref-index: "https://www.elastic.co/guide/en/apm/agent/nodejs" + apm-node-ref: "https://www.elastic.co/guide/en/apm/agent/nodejs/current" + apm-node-ref-1x: "https://www.elastic.co/guide/en/apm/agent/nodejs/1.x" + apm-rum-ref: "https://www.elastic.co/guide/en/apm/agent/rum-js/current" + apm-ruby-ref: "https://www.elastic.co/guide/en/apm/agent/ruby/current" + apm-java-ref: "https://www.elastic.co/guide/en/apm/agent/java/current" + apm-go-ref: "https://www.elastic.co/guide/en/apm/agent/go/current" + apm-dotnet-ref: "https://www.elastic.co/guide/en/apm/agent/dotnet/current" + apm-php-ref: "https://www.elastic.co/guide/en/apm/agent/php/current" + apm-ios-ref: "https://www.elastic.co/guide/en/apm/agent/swift/current" + apm-lambda-ref: "https://www.elastic.co/guide/en/apm/lambda/current" + apm-attacher-ref: "https://www.elastic.co/guide/en/apm/attacher/current" + docker-logging-ref: "https://www.elastic.co/guide/en/beats/loggingplugin/current" + esf-ref: "https://www.elastic.co/guide/en/esf/current" + kinesis-firehose-ref: "https://www.elastic.co/guide/en/kinesis/{{kinesis_version}}" + estc-welcome-current: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions/current" + estc-welcome: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions/current" + estc-welcome-all: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions" + hadoop-ref: "https://www.elastic.co/guide/en/elasticsearch/hadoop/current" + stack-ref: "https://www.elastic.co/guide/en/elastic-stack/current" + stack-ref-67: "https://www.elastic.co/guide/en/elastic-stack/6.7" + stack-ref-68: "https://www.elastic.co/guide/en/elastic-stack/6.8" + stack-ref-70: "https://www.elastic.co/guide/en/elastic-stack/7.0" + stack-ref-80: "https://www.elastic.co/guide/en/elastic-stack/8.0" + stack-ov: "https://www.elastic.co/guide/en/elastic-stack-overview/current" + stack-gs: "https://www.elastic.co/guide/en/elastic-stack-get-started/current" + stack-gs-current: "https://www.elastic.co/guide/en/elastic-stack-get-started/current" + javaclient: "https://www.elastic.co/guide/en/elasticsearch/client/java-api/current" + java-api-client: "https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current" + java-rest: "https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current" + jsclient: "https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current" + jsclient-current: "https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current" + es-ruby-client: "https://www.elastic.co/guide/en/elasticsearch/client/ruby-api/current" + es-dotnet-client: "https://www.elastic.co/guide/en/elasticsearch/client/net-api/current" + es-php-client: "https://www.elastic.co/guide/en/elasticsearch/client/php-api/current" + es-python-client: "https://www.elastic.co/guide/en/elasticsearch/client/python-api/current" + defguide: "https://www.elastic.co/guide/en/elasticsearch/guide/2.x" + painless: "https://www.elastic.co/guide/en/elasticsearch/painless/current" + plugins: "https://www.elastic.co/guide/en/elasticsearch/plugins/current" + plugins-8x: "https://www.elastic.co/guide/en/elasticsearch/plugins/8.1" + plugins-7x: "https://www.elastic.co/guide/en/elasticsearch/plugins/7.17" + plugins-6x: "https://www.elastic.co/guide/en/elasticsearch/plugins/6.8" + glossary: "https://www.elastic.co/guide/en/elastic-stack-glossary/current" + upgrade_guide: "https://www.elastic.co/products/upgrade_guide" + blog-ref: "https://www.elastic.co/blog/" + curator-ref: "https://www.elastic.co/guide/en/elasticsearch/client/curator/current" + curator-ref-current: "https://www.elastic.co/guide/en/elasticsearch/client/curator/current" + metrics-ref: "https://www.elastic.co/guide/en/metrics/current" + metrics-guide: "https://www.elastic.co/guide/en/metrics/guide/current" + logs-ref: "https://www.elastic.co/guide/en/logs/current" + logs-guide: "https://www.elastic.co/guide/en/logs/guide/current" + uptime-guide: "https://www.elastic.co/guide/en/uptime/current" + observability-guide: "https://www.elastic.co/guide/en/observability/current" + observability-guide-all: "https://www.elastic.co/guide/en/observability" + siem-guide: "https://www.elastic.co/guide/en/siem/guide/current" + security-guide: "https://www.elastic.co/guide/en/security/current" + security-guide-all: "https://www.elastic.co/guide/en/security" + endpoint-guide: "https://www.elastic.co/guide/en/endpoint/current" + sql-odbc: "https://www.elastic.co/guide/en/elasticsearch/sql-odbc/current" + ecs-ref: "https://www.elastic.co/guide/en/ecs/current" + ecs-logging-ref: "https://www.elastic.co/guide/en/ecs-logging/overview/current" + ecs-logging-go-logrus-ref: "https://www.elastic.co/guide/en/ecs-logging/go-logrus/current" + ecs-logging-go-zap-ref: "https://www.elastic.co/guide/en/ecs-logging/go-zap/current" + ecs-logging-go-zerolog-ref: "https://www.elastic.co/guide/en/ecs-logging/go-zap/current" + ecs-logging-java-ref: "https://www.elastic.co/guide/en/ecs-logging/java/current" + ecs-logging-dotnet-ref: "https://www.elastic.co/guide/en/ecs-logging/dotnet/current" + ecs-logging-nodejs-ref: "https://www.elastic.co/guide/en/ecs-logging/nodejs/current" + ecs-logging-php-ref: "https://www.elastic.co/guide/en/ecs-logging/php/current" + ecs-logging-python-ref: "https://www.elastic.co/guide/en/ecs-logging/python/current" + ecs-logging-ruby-ref: "https://www.elastic.co/guide/en/ecs-logging/ruby/current" + ml-docs: "https://www.elastic.co/guide/en/machine-learning/current" + eland-docs: "https://www.elastic.co/guide/en/elasticsearch/client/eland/current" + eql-ref: "https://eql.readthedocs.io/en/latest/query-guide" + extendtrial: "https://www.elastic.co/trialextension" + wikipedia: "https://en.wikipedia.org/wiki" + forum: "https://discuss.elastic.co/" + xpack-forum: "https://discuss.elastic.co/c/50-x-pack" + security-forum: "https://discuss.elastic.co/c/x-pack/shield" + watcher-forum: "https://discuss.elastic.co/c/x-pack/watcher" + monitoring-forum: "https://discuss.elastic.co/c/x-pack/marvel" + graph-forum: "https://discuss.elastic.co/c/x-pack/graph" + apm-forum: "https://discuss.elastic.co/c/apm" + enterprise-search-ref: "https://www.elastic.co/guide/en/enterprise-search/current" + app-search-ref: "https://www.elastic.co/guide/en/app-search/current" + workplace-search-ref: "https://www.elastic.co/guide/en/workplace-search/current" + enterprise-search-node-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/enterprise-search-node/current" + enterprise-search-php-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/php/current" + enterprise-search-python-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/python/current" + enterprise-search-ruby-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/ruby/current" + elastic-maps-service: "https://maps.elastic.co" + integrations-docs: "https://docs.elastic.co/en/integrations" + integrations-devguide: "https://www.elastic.co/guide/en/integrations-developer/current" + time-units: "https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#time-units" + byte-units: "https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units" + apm-py-ref-v: "https://www.elastic.co/guide/en/apm/agent/python/current" + apm-node-ref-v: "https://www.elastic.co/guide/en/apm/agent/nodejs/current" + apm-rum-ref-v: "https://www.elastic.co/guide/en/apm/agent/rum-js/current" + apm-ruby-ref-v: "https://www.elastic.co/guide/en/apm/agent/ruby/current" + apm-java-ref-v: "https://www.elastic.co/guide/en/apm/agent/java/current" + apm-go-ref-v: "https://www.elastic.co/guide/en/apm/agent/go/current" + apm-ios-ref-v: "https://www.elastic.co/guide/en/apm/agent/swift/current" + apm-dotnet-ref-v: "https://www.elastic.co/guide/en/apm/agent/dotnet/current" + apm-php-ref-v: "https://www.elastic.co/guide/en/apm/agent/php/current" + ecloud: "Elastic Cloud" + esf: "Elastic Serverless Forwarder" + ess: "Elasticsearch Service" + ece: "Elastic Cloud Enterprise" + eck: "Elastic Cloud on Kubernetes" + serverless-full: "Elastic Cloud Serverless" + serverless-short: "Serverless" + es-serverless: "Elasticsearch Serverless" + es3: "Elasticsearch Serverless" + obs-serverless: "Elastic Observability Serverless" + sec-serverless: "Elastic Security Serverless" + serverless-docs: "https://docs.elastic.co/serverless" + cloud: "https://www.elastic.co/guide/en/cloud/current" + ess-utm-params: "?page=docs&placement=docs-body" + ess-baymax: "?page=docs&placement=docs-body" + ess-trial: "https://cloud.elastic.co/registration?page=docs&placement=docs-body" + ess-product: "https://www.elastic.co/cloud/elasticsearch-service?page=docs&placement=docs-body" + ess-console: "https://cloud.elastic.co?page=docs&placement=docs-body" + ess-console-name: "Elasticsearch Service Console" + ess-deployments: "https://cloud.elastic.co/deployments?page=docs&placement=docs-body" + ece-ref: "https://www.elastic.co/guide/en/cloud-enterprise/current" + eck-ref: "https://www.elastic.co/guide/en/cloud-on-k8s/current" + ess-leadin: "You can run Elasticsearch on your own hardware or use our hosted Elasticsearch Service that is available on AWS, GCP, and Azure. https://cloud.elastic.co/registration{ess-utm-params}[Try the Elasticsearch Service for free]." + ess-leadin-short: "Our hosted Elasticsearch Service is available on AWS, GCP, and Azure, and you can https://cloud.elastic.co/registration{ess-utm-params}[try it for free]." + ess-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg[link=\"https://cloud.elastic.co/registration{ess-utm-params}\", title=\"Supported on Elasticsearch Service\"]" + ece-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud_ece.svg[link=\"https://cloud.elastic.co/registration{ess-utm-params}\", title=\"Supported on Elastic Cloud Enterprise\"]" + cloud-only: "This feature is designed for indirect use by https://cloud.elastic.co/registration{ess-utm-params}[Elasticsearch Service], https://www.elastic.co/guide/en/cloud-enterprise/{ece-version-link}[Elastic Cloud Enterprise], and https://www.elastic.co/guide/en/cloud-on-k8s/current[Elastic Cloud on Kubernetes]. Direct use is not supported." + ess-setting-change: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg[link=\"{ess-trial}\", title=\"Supported on {ess}\"] indicates a change to a supported https://www.elastic.co/guide/en/cloud/current/ec-add-user-settings.html[user setting] for Elasticsearch Service." + ess-skip-section: "If you use Elasticsearch Service, skip this section. Elasticsearch Service handles these changes for you." + api-cloud: "https://www.elastic.co/docs/api/doc/cloud" + api-ece: "https://www.elastic.co/docs/api/doc/cloud-enterprise" + api-kibana-serverless: "https://www.elastic.co/docs/api/doc/serverless" + es-feature-flag: "This feature is in development and not yet available for use. This documentation is provided for informational purposes only." + es-ref-dir: "'{{elasticsearch-root}}/docs/reference'" + apm-app: "APM app" + uptime-app: "Uptime app" + synthetics-app: "Synthetics app" + logs-app: "Logs app" + metrics-app: "Metrics app" + infrastructure-app: "Infrastructure app" + siem-app: "SIEM app" + security-app: "Elastic Security app" + ml-app: "Machine Learning" + dev-tools-app: "Dev Tools" + ingest-manager-app: "Ingest Manager" + stack-manage-app: "Stack Management" + stack-monitor-app: "Stack Monitoring" + alerts-ui: "Alerts and Actions" + rules-ui: "Rules" + rac-ui: "Rules and Connectors" + connectors-ui: "Connectors" + connectors-feature: "Actions and Connectors" + stack-rules-feature: "Stack Rules" + user-experience: "User Experience" + ems: "Elastic Maps Service" + ems-init: "EMS" + hosted-ems: "Elastic Maps Server" + ipm-app: "Index Pattern Management" + ingest-pipelines: "ingest pipelines" + ingest-pipelines-app: "Ingest Pipelines" + ingest-pipelines-cap: "Ingest pipelines" + ls-pipelines: "Logstash pipelines" + ls-pipelines-app: "Logstash Pipelines" + maint-windows: "maintenance windows" + maint-windows-app: "Maintenance Windows" + maint-windows-cap: "Maintenance windows" + custom-roles-app: "Custom Roles" + data-source: "data view" + data-sources: "data views" + data-source-caps: "Data View" + data-sources-caps: "Data Views" + data-source-cap: "Data view" + data-sources-cap: "Data views" + project-settings: "Project settings" + manage-app: "Management" + index-manage-app: "Index Management" + data-views-app: "Data Views" + rules-app: "Rules" + saved-objects-app: "Saved Objects" + tags-app: "Tags" + api-keys-app: "API keys" + transforms-app: "Transforms" + connectors-app: "Connectors" + files-app: "Files" + reports-app: "Reports" + maps-app: "Maps" + alerts-app: "Alerts" + crawler: "Enterprise Search web crawler" + ents: "Enterprise Search" + app-search-crawler: "App Search web crawler" + agent: "Elastic Agent" + agents: "Elastic Agents" + fleet: "Fleet" + fleet-server: "Fleet Server" + integrations-server: "Integrations Server" + ingest-manager: "Ingest Manager" + ingest-management: "ingest management" + package-manager: "Elastic Package Manager" + integrations: "Integrations" + package-registry: "Elastic Package Registry" + artifact-registry: "Elastic Artifact Registry" + aws: "AWS" + stack: "Elastic Stack" + xpack: "X-Pack" + es: "Elasticsearch" + kib: "Kibana" + esms: "Elastic Stack Monitoring Service" + esms-init: "ESMS" + ls: "Logstash" + beats: "Beats" + auditbeat: "Auditbeat" + filebeat: "Filebeat" + heartbeat: "Heartbeat" + metricbeat: "Metricbeat" + packetbeat: "Packetbeat" + winlogbeat: "Winlogbeat" + functionbeat: "Functionbeat" + journalbeat: "Journalbeat" + es-sql: "Elasticsearch SQL" + esql: "ES|QL" + elastic-agent: "Elastic Agent" + k8s: "Kubernetes" + log-driver-long: "Elastic Logging Plugin for Docker" + security: "X-Pack security" + security-features: "security features" + operator-feature: "operator privileges feature" + es-security-features: "Elasticsearch security features" + stack-security-features: "Elastic Stack security features" + endpoint-sec: "Endpoint Security" + endpoint-cloud-sec: "Endpoint and Cloud Security" + elastic-defend: "Elastic Defend" + elastic-sec: "Elastic Security" + elastic-endpoint: "Elastic Endpoint" + swimlane: "Swimlane" + sn: "ServiceNow" + sn-itsm: "ServiceNow ITSM" + sn-itom: "ServiceNow ITOM" + sn-sir: "ServiceNow SecOps" + jira: "Jira" + ibm-r: "IBM Resilient" + webhook: "Webhook" + webhook-cm: "Webhook - Case Management" + opsgenie: "Opsgenie" + bedrock: "Amazon Bedrock" + gemini: "Google Gemini" + hive: "TheHive" + monitoring: "X-Pack monitoring" + monitor-features: "monitoring features" + stack-monitor-features: "Elastic Stack monitoring features" + watcher: "Watcher" + alert-features: "alerting features" + reporting: "X-Pack reporting" + report-features: "reporting features" + graph: "X-Pack graph" + graph-features: "graph analytics features" + searchprofiler: "Search Profiler" + xpackml: "X-Pack machine learning" + ml: "machine learning" + ml-cap: "Machine learning" + ml-init: "ML" + ml-features: "machine learning features" + stack-ml-features: "Elastic Stack machine learning features" + ccr: "cross-cluster replication" + ccr-cap: "Cross-cluster replication" + ccr-init: "CCR" + ccs: "cross-cluster search" + ccs-cap: "Cross-cluster search" + ccs-init: "CCS" + ilm: "index lifecycle management" + ilm-cap: "Index lifecycle management" + ilm-init: "ILM" + dlm: "data lifecycle management" + dlm-cap: "Data lifecycle management" + dlm-init: "DLM" + search-snap: "searchable snapshot" + search-snaps: "searchable snapshots" + search-snaps-cap: "Searchable snapshots" + slm: "snapshot lifecycle management" + slm-cap: "Snapshot lifecycle management" + slm-init: "SLM" + rollup-features: "data rollup features" + ipm: "index pattern management" + ipm-cap: "Index pattern" + rollup: "rollup" + rollup-cap: "Rollup" + rollups: "rollups" + rollups-cap: "Rollups" + rollup-job: "rollup job" + rollup-jobs: "rollup jobs" + rollup-jobs-cap: "Rollup jobs" + dfeed: "datafeed" + dfeeds: "datafeeds" + dfeed-cap: "Datafeed" + dfeeds-cap: "Datafeeds" + ml-jobs: "machine learning jobs" + ml-jobs-cap: "Machine learning jobs" + anomaly-detect: "anomaly detection" + anomaly-detect-cap: "Anomaly detection" + anomaly-job: "anomaly detection job" + anomaly-jobs: "anomaly detection jobs" + anomaly-jobs-cap: "Anomaly detection jobs" + dataframe: "data frame" + dataframes: "data frames" + dataframe-cap: "Data frame" + dataframes-cap: "Data frames" + watcher-transform: "payload transform" + watcher-transforms: "payload transforms" + watcher-transform-cap: "Payload transform" + watcher-transforms-cap: "Payload transforms" + transform: "transform" + transforms: "transforms" + transform-cap: "Transform" + transforms-cap: "Transforms" + dataframe-transform: "transform" + dataframe-transform-cap: "Transform" + dataframe-transforms: "transforms" + dataframe-transforms-cap: "Transforms" + dfanalytics-cap: "Data frame analytics" + dfanalytics: "data frame analytics" + dataframe-analytics-config: "'{dataframe} analytics config'" + dfanalytics-job: "'{dataframe} analytics job'" + dfanalytics-jobs: "'{dataframe} analytics jobs'" + dfanalytics-jobs-cap: "'{dataframe-cap} analytics jobs'" + cdataframe: "continuous data frame" + cdataframes: "continuous data frames" + cdataframe-cap: "Continuous data frame" + cdataframes-cap: "Continuous data frames" + cdataframe-transform: "continuous transform" + cdataframe-transforms: "continuous transforms" + cdataframe-transforms-cap: "Continuous transforms" + ctransform: "continuous transform" + ctransform-cap: "Continuous transform" + ctransforms: "continuous transforms" + ctransforms-cap: "Continuous transforms" + oldetection: "outlier detection" + oldetection-cap: "Outlier detection" + olscore: "outlier score" + olscores: "outlier scores" + fiscore: "feature influence score" + evaluatedf-api: "evaluate {dataframe} analytics API" + evaluatedf-api-cap: "Evaluate {dataframe} analytics API" + binarysc: "binary soft classification" + binarysc-cap: "Binary soft classification" + regression: "regression" + regression-cap: "Regression" + reganalysis: "regression analysis" + reganalysis-cap: "Regression analysis" + depvar: "dependent variable" + feature-var: "feature variable" + feature-vars: "feature variables" + feature-vars-cap: "Feature variables" + classification: "classification" + classification-cap: "Classification" + classanalysis: "classification analysis" + classanalysis-cap: "Classification analysis" + infer-cap: "Inference" + infer: "inference" + lang-ident-cap: "Language identification" + lang-ident: "language identification" + data-viz: "Data Visualizer" + file-data-viz: "File Data Visualizer" + feat-imp: "feature importance" + feat-imp-cap: "Feature importance" + nlp: "natural language processing" + nlp-cap: "Natural language processing" + apm-agent: "APM agent" + apm-go-agent: "Elastic APM Go agent" + apm-go-agents: "Elastic APM Go agents" + apm-ios-agent: "Elastic APM iOS agent" + apm-ios-agents: "Elastic APM iOS agents" + apm-java-agent: "Elastic APM Java agent" + apm-java-agents: "Elastic APM Java agents" + apm-dotnet-agent: "Elastic APM .NET agent" + apm-dotnet-agents: "Elastic APM .NET agents" + apm-node-agent: "Elastic APM Node.js agent" + apm-node-agents: "Elastic APM Node.js agents" + apm-php-agent: "Elastic APM PHP agent" + apm-php-agents: "Elastic APM PHP agents" + apm-py-agent: "Elastic APM Python agent" + apm-py-agents: "Elastic APM Python agents" + apm-ruby-agent: "Elastic APM Ruby agent" + apm-ruby-agents: "Elastic APM Ruby agents" + apm-rum-agent: "Elastic APM Real User Monitoring (RUM) JavaScript agent" + apm-rum-agents: "Elastic APM RUM JavaScript agents" + apm-lambda-ext: "Elastic APM AWS Lambda extension" + project-monitors: "project monitors" + project-monitors-cap: "Project monitors" + private-location: "Private Location" + private-locations: "Private Locations" + pwd: "YOUR_PASSWORD" + esh: "ES-Hadoop" + default-dist: "default distribution" + oss-dist: "OSS-only distribution" + observability: "Observability" + api-request-title: "Request" + api-prereq-title: "Prerequisites" + api-description-title: "Description" + api-path-parms-title: "Path parameters" + api-query-parms-title: "Query parameters" + api-request-body-title: "Request body" + api-response-codes-title: "Response codes" + api-response-body-title: "Response body" + api-example-title: "Example" + api-examples-title: "Examples" + api-definitions-title: "Properties" + multi-arg: "†footnoteref:[multi-arg,This parameter accepts multiple arguments.]" + multi-arg-ref: "†footnoteref:[multi-arg]" + yes-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png[Yes,20,15]" + no-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png[No,20,15]" + es-repo: "https://github.com/elastic/elasticsearch/" + es-issue: "https://github.com/elastic/elasticsearch/issues/" + es-pull: "https://github.com/elastic/elasticsearch/pull/" + es-commit: "https://github.com/elastic/elasticsearch/commit/" + kib-repo: "https://github.com/elastic/kibana/" + kib-issue: "https://github.com/elastic/kibana/issues/" + kibana-issue: "'{kib-repo}issues/'" + kib-pull: "https://github.com/elastic/kibana/pull/" + kibana-pull: "'{kib-repo}pull/'" + kib-commit: "https://github.com/elastic/kibana/commit/" + ml-repo: "https://github.com/elastic/ml-cpp/" + ml-issue: "https://github.com/elastic/ml-cpp/issues/" + ml-pull: "https://github.com/elastic/ml-cpp/pull/" + ml-commit: "https://github.com/elastic/ml-cpp/commit/" + apm-repo: "https://github.com/elastic/apm-server/" + apm-issue: "https://github.com/elastic/apm-server/issues/" + apm-pull: "https://github.com/elastic/apm-server/pull/" + kibana-blob: "https://github.com/elastic/kibana/blob/current/" + apm-get-started-ref: "https://www.elastic.co/guide/en/apm/get-started/current" + apm-server-ref: "https://www.elastic.co/guide/en/apm/server/current" + apm-server-ref-v: "https://www.elastic.co/guide/en/apm/server/current" + apm-server-ref-m: "https://www.elastic.co/guide/en/apm/server/master" + apm-server-ref-62: "https://www.elastic.co/guide/en/apm/server/6.2" + apm-server-ref-64: "https://www.elastic.co/guide/en/apm/server/6.4" + apm-server-ref-70: "https://www.elastic.co/guide/en/apm/server/7.0" + apm-overview-ref-v: "https://www.elastic.co/guide/en/apm/get-started/current" + apm-overview-ref-70: "https://www.elastic.co/guide/en/apm/get-started/7.0" + apm-overview-ref-m: "https://www.elastic.co/guide/en/apm/get-started/master" + infra-guide: "https://www.elastic.co/guide/en/infrastructure/guide/current" + a-data-source: "a data view" + icon-bug: "pass:[]" + icon-checkInCircleFilled: "pass:[]" + icon-warningFilled: "pass:[]" diff --git a/docs/index.asciidoc b/docs/index.asciidoc deleted file mode 100644 index 6284e21e..00000000 --- a/docs/index.asciidoc +++ /dev/null @@ -1,17 +0,0 @@ -:ecs-repo-dir: {ecs-logging-root}/docs/ - -include::{docs-root}/shared/versions/stack/current.asciidoc[] -include::{docs-root}/shared/attributes.asciidoc[] - -ifdef::env-github[] -NOTE: For the best reading experience, -please view this documentation at https://www.elastic.co/guide/en/ecs-logging/java/current/index.html[elastic.co] -endif::[] - -= ECS Logging Java Reference - -ifndef::env-github[] -include::./intro.asciidoc[Introduction] -include::./setup.asciidoc[Set up] -include::./structured-logging-log4j2.asciidoc[Structured logging with log4j2] -endif::[] diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc deleted file mode 100644 index fa4f6545..00000000 --- a/docs/intro.asciidoc +++ /dev/null @@ -1,16 +0,0 @@ -[[intro]] -== Introduction - -ECS loggers are formatter/encoder plugins for your favorite logging libraries. -They make it easy to format your logs into ECS-compatible JSON. - -Ready to jump into `ecs-logging-java`? <>. - -[TIP] -==== -Want to learn more about ECS, ECS logging, and other available language plugins? -See the {ecs-logging-ref}/intro.html[ECS logging guide]. - -Want to learn more about the Elastic APM Java agent logging features? -See {apm-java-ref}/logs.html[Logs]. -==== diff --git a/docs/reference/_structured_logging_with_log4j2.md b/docs/reference/_structured_logging_with_log4j2.md new file mode 100644 index 00000000..a37af819 --- /dev/null +++ b/docs/reference/_structured_logging_with_log4j2.md @@ -0,0 +1,65 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/ecs-logging/java/current/_structured_logging_with_log4j2.html +--- + +# Structured logging with log4j2 [_structured_logging_with_log4j2] + +By leveraging log4j2’s `MapMessage` or even by implementing your own `MultiformatMessage` with JSON support, you can add additional fields to the resulting JSON. + +Example: + +```java +logger.info(new StringMapMessage() + .with("message", "Hello World!") + .with("foo", "bar")); +``` + +If Jackson is on the classpath, you can also use an `ObjectMessage` to add a custom object the resulting JSON. + +```java +logger.info(new ObjectMessage(myObject)); +``` + +The `myObject` variable refers to a custom object which can be serialized by a Jackson `ObjectMapper`. + +Using either will merge the object at the top-level (not nested under `message`) of the log event if it is a JSON object. If it’s a string, number boolean, or array, it will be converted into a string and added as the `message` property. This conversion avoids mapping conflicts as `message` is typed as a string in the Elasticsearch mapping. + + +## Tips [_tips] + +We recommend using existing [ECS fields](ecs://docs/reference/ecs-field-reference.md). + +If there is no appropriate ECS field, consider prefixing your fields with `labels.`, as in `labels.foo`, for simple key/value pairs. For nested structures, consider prefixing with `custom.`. This approach protects against conflicts in case ECS later adds the same fields but with a different mapping. + + +## Gotchas [_gotchas] + +A common pitfall is how dots in field names are handled in Elasticsearch and how they affect the mapping. In recent Elasticsearch versions, the following JSON structures would result in the same index mapping: + +```json +{ + "foo.bar": "baz" +} +``` + +```json +{ + "foo": { + "bar": "baz" + } +} +``` + +The property `foo` would be mapped to the [Object datatype](elasticsearch://docs/reference/elasticsearch/mapping-reference/object.md). + +This means that you can’t index a document where `foo` would be a different datatype, as in shown in the following example: + +```json +{ + "foo": "bar" +} +``` + +In that example, `foo` is a string. Trying to index that document results in an error because the data type of `foo` can’t be object and string at the same time. + diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 00000000..c8b75111 --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1,20 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/ecs-logging/java/current/intro.html + - https://www.elastic.co/guide/en/ecs-logging/java/current/index.html +--- + +# ECS Logging Java [intro] + +ECS loggers are formatter/encoder plugins for your favorite logging libraries. They make it easy to format your logs into ECS-compatible JSON. + +Ready to jump into `ecs-logging-java`? [Get started](/reference/setup.md). + +::::{tip} +Want to learn more about ECS, ECS logging, and other available language plugins? See the [ECS logging guide](ecs-logging://docs/reference/intro.md). + +Want to learn more about the Elastic APM Java agent logging features? See [Logs](apm-agent-java://docs/reference/logs.md). + +:::: + + diff --git a/docs/reference/setup.md b/docs/reference/setup.md new file mode 100644 index 00000000..6731f0c5 --- /dev/null +++ b/docs/reference/setup.md @@ -0,0 +1,503 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/ecs-logging/java/current/setup.html +navigation_title: Get started +--- + +# Get started with ECS Logging Java [setup] + + +## Step 1: Configure application logging [setup-step-1] + +If you are using the Elastic APM Java agent, the easiest way to transform your logs into ECS-compatible JSON format is through the [`log_ecs_reformatting`](apm-agent-java://docs/reference/config-logging.md#config-log-ecs-reformatting) configuration option. By only setting this option, the Java agent will automatically import the correct ECS-logging library and configure your logging framework to use it instead (`OVERRIDE`/`REPLACE`) or in addition to (`SHADE`) your current configuration. No other changes required! Make sure to check out other [Logging configuration options](apm-agent-java://docs/reference/config-logging.md) to unlock the full potential of this option. + +Otherwise, follow the steps below to manually apply ECS-formatting through your logging framework configuration. The following logging frameworks are supported: + +* Logback (default for Spring Boot) +* Log4j2 +* Log4j +* `java.util.logging` (JUL) +* JBoss Log Manager + + +### Add the dependency [_add_the_dependency] + +:::::::{tab-set} + +::::::{tab-item} Logback +The minimum required logback version is 1.1. + +Download the latest version of Elastic logging: [![Maven Central](https://img.shields.io/maven-central/v/co.elastic.logging/logback-ecs-encoder.svg)](https://search.maven.org/search?q=g:co.elastic.logging%20AND%20a:logback-ecs-encoder) + +Add a dependency to your application: + +```xml + + co.elastic.logging + logback-ecs-encoder + ${ecs-logging-java.version} + +``` + +::::{note} +If you are not using a dependency management tool, like maven, you have to manually add both `logback-ecs-encoder` and `ecs-logging-core` jars to the classpath. For example to the `$CATALINA_HOME/lib` directory. Other than that, there are no required dependencies. +:::: +:::::: + +::::::{tab-item} Log4j2 +The minimum required log4j2 version is 2.6. + +Download the latest version of Elastic logging: [![Maven Central](https://img.shields.io/maven-central/v/co.elastic.logging/log4j2-ecs-layout.svg)](https://search.maven.org/search?q=g:co.elastic.logging%20AND%20a:log4j2-ecs-layout:) + +Add a dependency to your application: + +```xml + + co.elastic.logging + log4j2-ecs-layout + ${ecs-logging-java.version} + +``` + +::::{note} +If you are not using a dependency management tool, like maven, you have to manually add both `log4j2-ecs-layout` and `ecs-logging-core` jars to the classpath. For example, to the `$CATALINA_HOME/lib` directory. Other than that, there are no required dependencies. +:::: +:::::: + +::::::{tab-item} Log4j +The minimum required log4j version is 1.2.4. + +Download the latest version of Elastic logging: [![Maven Central](https://img.shields.io/maven-central/v/co.elastic.logging/log4j-ecs-layout.svg)](https://search.maven.org/search?q=g:co.elastic.logging%20AND%20a:log4j-ecs-layout) + +Add a dependency to your application: + +```xml + + co.elastic.logging + log4j-ecs-layout + ${ecs-logging-java.version} + +``` + +::::{note} +If you are not using a dependency management tool, like maven, you have to manually add both `log4j-ecs-layout` and `ecs-logging-core` jars to the classpath. For example, to the `$CATALINA_HOME/lib` directory. Other than that, there are no required dependencies. +:::: +:::::: + +::::::{tab-item} JUL +A formatter for JUL (`java.util.logging`) which produces ECS-compatible records. Useful for applications that use JUL as primary logging framework, like Apache Tomcat. + +Download the latest version of Elastic logging: [![Maven Central](https://img.shields.io/maven-central/v/co.elastic.logging/jul-ecs-formatter.svg)](https://search.maven.org/search?q=g:co.elastic.logging%20AND%20a:jul-ecs-formatter) + +Add a dependency to your application: + +```xml + + co.elastic.logging + jul-ecs-formatter + ${ecs-logging-java.version} + +``` + +::::{note} +If you are not using a dependency management tool, like maven, you have to manually add both `jul-ecs-formatter` and `ecs-logging-core` jars to the classpath. For example, to the `$CATALINA_HOME/lib` directory. Other than that, there are no required dependencies. +:::: +:::::: + +::::::{tab-item} JBoss +A formatter for JBoss Log Manager which produces ECS-compatible records. Useful for applications that use JBoss Log Manager as their primary logging framework, like WildFly. + +Download the latest version of Elastic logging: [![Maven Central](https://img.shields.io/maven-central/v/co.elastic.logging/jboss-logmanager-ecs-formatter.svg)](https://search.maven.org/search?q=g:co.elastic.logging%20AND%20a:jboss-logmanager-ecs-formatter) + +Add a dependency to your application: + +```xml + + co.elastic.logging + jboss-logmanager-ecs-formatter + ${ecs-logging-java.version} + +``` + +::::{note} +If you are not using a dependency management tool, like maven, you have to manually add both `jboss-logmanager-ecs-formatter` and `ecs-logging-core` jars to the classpath. Other than that, there are no required dependencies. +:::: +:::::: + +::::::: + +### Use the ECS encoder/formatter/layout [_use_the_ecs_encoderformatterlayout] + +:::::::{tab-set} + +::::::{tab-item} Logback +**Spring Boot applications** + +In `src/main/resources/logback-spring.xml`: + +```xml + + + + + + + + + + + + + + + +``` + +You also need to configure the following properties to your `application.properties`: + +```properties +spring.application.name=my-application +# for Spring Boot 2.2.x+ +logging.file.name=/path/to/my-application.log +# for older Spring Boot versions +logging.file=/path/to/my-application.log +``` + +**Other applications** + +All you have to do is to use the `co.elastic.logging.logback.EcsEncoder` instead of the default pattern encoder in `logback.xml` + +```xml + + my-application + my-application-version + my-application-environment + my-application-cluster-node + +``` + +**Encoder Parameters** + +| Parameter name | Type | Default | Description | +| --- | --- | --- | --- | +| `serviceName` | String | | Sets the `service.name` field so you can filter your logs by a particular service name | +| `serviceVersion` | String | | Sets the `service.version` field so you can filter your logs by a particular service version | +| `serviceEnvironment` | String | | Sets the `service.environment` field so you can filter your logs by a particular service environment | +| `serviceNodeName` | String | | Sets the `service.node.name` field so you can filter your logs by a particular node of your clustered service | +| `eventDataset` | String | `${serviceName}` | Sets the `event.dataset` field used by the machine learning job of the Logs app to look for anomalies in the log rate. | +| `includeMarkers` | boolean | `false` | Log [Markers](https://logging.apache.org/log4j/2.0/manual/markers.md) as [`tags`](ecs://docs/reference/ecs-base.md) | +| `stackTraceAsArray` | boolean | `false` | Serializes the [`error.stack_trace`](ecs://docs/reference/ecs-error.md) as a JSON array where each element is in a new line to improve readability.Note that this requires a slightly more complex [Filebeat configuration](#setup-stack-trace-as-array). | +| `includeOrigin` | boolean | `false` | If `true`, adds the [`log.origin.file.name`](ecs://docs/reference/ecs-log.md), [`log.origin.file.line`](ecs://docs/reference/ecs-log.md) and [`log.origin.function`](ecs://docs/reference/ecs-log.md) fields. Note that you also have to set `true` on your appenders if you are using the async ones. | + +To include any custom field in the output, use following syntax: + +```xml + + key1 + value1 + + + key2 + value2 + +``` +:::::: + +::::::{tab-item} Log4j2 +Instead of the usual ``, use ``. For example: + +```xml + + + + + + + + + + + + + + + + + +``` + +**Layout Parameters** + +| Parameter name | Type | Default | Description | +| --- | --- | --- | --- | +| `serviceName` | String | | Sets the `service.name` field so you can filter your logs by a particular service name | +| `serviceVersion` | String | | Sets the `service.version` field so you can filter your logs by a particular service version | +| `serviceEnvironment` | String | | Sets the `service.environment` field so you can filter your logs by a particular service environment | +| `serviceNodeName` | String | | Sets the `service.node.name` field so you can filter your logs by a particular node of your clustered service | +| `eventDataset` | String | `${serviceName}` | Sets the `event.dataset` field used by the machine learning job of the Logs app to look for anomalies in the log rate. | +| `includeMarkers` | boolean | `false` | Log [Markers](https://logging.apache.org/log4j/2.0/manual/markers.md) as [`tags`](ecs://docs/reference/ecs-base.md) | +| `stackTraceAsArray` | boolean | `false` | Serializes the [`error.stack_trace`](ecs://docs/reference/ecs-error.md) as a JSON array where each element is in a new line to improve readability. Note that this requires a slightly more complex [Filebeat configuration](#setup-stack-trace-as-array). | +| `includeOrigin` | boolean | `false` | If `true`, adds the [`log.origin.file.name`](ecs://docs/reference/ecs-log.md) fields. Note that you also have to set `includeLocation="true"` on your loggers and appenders if you are using the async ones. | + +To include any custom field in the output, use following syntax: + +```xml + + + + +``` + +Custom fields are included in the order they are declared. The values support [lookups](https://logging.apache.org/log4j/2.x/manual/lookups.md). This means that the `KeyValuePair` setting can be utilized to dynamically set predefined fields as well: + +```xml + + + + +``` + +::::{note} +The log4j2 `EcsLayout` does not allocate any memory (unless the log event contains an `Exception`) to reduce GC pressure. This is achieved by manually serializing JSON so that no intermediate JSON or map representation of a log event is needed. +:::: +:::::: + +::::::{tab-item} Log4j +Instead of the usual layout class `"org.apache.log4j.PatternLayout"`, use `"co.elastic.logging.log4j.EcsLayout"`. For example: + +```xml + + + + + + + + + + + + + + + + + + + + + + + +``` + +**Layout Parameters** + +| Parameter name | Type | Default | Description | +| --- | --- | --- | --- | +| `serviceName` | String | | Sets the `service.name` field so you can filter your logs by a particular service name | +| `serviceVersion` | String | | Sets the `service.version` field so you can filter your logs by a particular service version | +| `serviceEnvironment` | String | | Sets the `service.environment` field so you can filter your logs by a particular service environment | +| `serviceNodeName` | String | | Sets the `service.node.name` field so you can filter your logs by a particular node of your clustered service | +| `eventDataset` | String | `${serviceName}` | Sets the `event.dataset` field used by the machine learning job of the Logs app to look for anomalies in the log rate. | +| `stackTraceAsArray` | boolean | `false` | Serializes the [`error.stack_trace`](ecs://docs/reference/ecs-error.md) as a JSON array where each element is in a new line to improve readability.Note that this requires a slightly more complex [Filebeat configuration](#setup-stack-trace-as-array). | +| `includeOrigin` | boolean | `false` | If `true`, adds the [`log.origin.file.name`](ecs://docs/reference/ecs-log.md) fields.Note that you also have to set `` if you are using `AsyncAppender`. | + +To include any custom field in the output, use following syntax: + +```xml + + + + +``` + +Custom fields are included in the order they are declared. +:::::: + +::::::{tab-item} JUL +Specify `co.elastic.logging.jul.EcsFormatter` as `formatter` for the required log handler. + +For example, in `$CATALINA_HOME/conf/logging.properties`: + +```properties +java.util.logging.ConsoleHandler.level = FINE +java.util.logging.ConsoleHandler.formatter = co.elastic.logging.jul.EcsFormatter +co.elastic.logging.jul.EcsFormatter.serviceName=my-app +co.elastic.logging.jul.EcsFormatter.serviceVersion=my-app-version +co.elastic.logging.jul.EcsFormatter.serviceEnvironment=my-app-environment +co.elastic.logging.jul.EcsFormatter.serviceNodeName=my-app-cluster-node +``` + +**Layout Parameters** + +| Parameter name | Type | Default | Description | +| --- | --- | --- | --- | +| `serviceName` | String | | Sets the `service.name` field so you can filter your logs by a particular service name | +| `serviceVersion` | String | | Sets the `service.version` field so you can filter your logs by a particular service version | +| `serviceEnvironment` | String | | Sets the `service.environment` field so you can filter your logs by a particular service environment | +| `serviceNodeName` | String | | Sets the `service.node.name` field so you can filter your logs by a particular node of your clustered service | +| `eventDataset` | String | `${serviceName}` | Sets the `event.dataset` field used by the machine learning job of the Logs app to look for anomalies in the log rate. | +| `stackTraceAsArray` | boolean | `false` | Serializes the [`error.stack_trace`](ecs://docs/reference/ecs-error.md) as a JSON array where each element is in a new line to improve readability. Note that this requires a slightly more complex Filebeat configuration. | +| `includeOrigin` | boolean | `false` | If `true`, adds the [`log.origin.file.name`](ecs://docs/reference/ecs-log.md) fields. Note that JUL does not stores line number and `log.origin.file.line` will have *1* value. | +| `additionalFields` | String | | Adds additional static fields to all log events. The fields are specified as comma-separated key-value pairs. Example: `co.elastic.logging.jul.EcsFormatter.additionalFields=key1=value1,key2=value2`. | +:::::: + +::::::{tab-item} JBoss +Specify `co.elastic.logging.jboss.logmanager.EcsFormatter` as `formatter` for the required log handler. + +For example, with Wildfly, create a `jboss-logmanager-ecs-formatter` module: + +```bash +$WILDFLY_HOME/bin/jboss-cli.sh -c 'module add --name=co.elastic.logging.jboss-logmanager-ecs-formatter --resources=jboss-logmanager-ecs-formatter-${ecs-logging-java.version}.jar:/tmp/ecs-logging-core-${ecs-logging-java.version}.jar --dependencies=org.jboss.logmanager' +``` + +Add the formatter to a handler in the logging subsystem: + +```bash +$WILDFLY_HOME/bin/jboss-cli.sh -c '/subsystem=logging/custom-formatter=ECS:add(module=co.elastic.logging.jboss-logmanager-ecs-formatter, +class=co.elastic.logging.jboss.logmanager.EcsFormatter, properties={serviceName=my-app,serviceVersion=my-app-version,serviceEnvironment=my-app-environment,serviceNodeName=my-app-cluster-node}),\ + /subsystem=logging/console-handler=CONSOLE:write-attribute(name=named-formatter,value=ECS)' +``` + +**Layout Parameters** + +| Parameter name | Type | Default | Description | +| --- | --- | --- | --- | +| `serviceName` | String | | Sets the `service.name` field so you can filter your logs by a particular service name | +| `serviceVersion` | String | | Sets the `service.version` field so you can filter your logs by a particular service version | +| `serviceEnvironment` | String | | Sets the `service.environment` field so you can filter your logs by a particular service environment | +| `serviceNodeName` | String | | Sets the `service.node.name` field so you can filter your logs by a particular node of your clustered service | +| `eventDataset` | String | `${serviceName}` | Sets the `event.dataset` field used by the machine learning job of the Logs app to look for anomalies in the log rate. | +| `stackTraceAsArray` | boolean | `false` | Serializes the [`error.stack_trace`](ecs://docs/reference/ecs-error.md) as a JSON array where each element is in a new line to improve readability. Note that this requires a slightly more complex [Filebeat configuration](#setup-stack-trace-as-array). | +| `includeOrigin` | boolean | `false` | If `true`, adds the [`log.origin.file.name`](ecs://docs/reference/ecs-log.md) fields. | +| `additionalFields` | String | | Adds additional static fields to all log events. The fields are specified as comma-separated key-value pairs. Example: `additionalFields=key1=value1,key2=value2`. | +:::::: + +::::::: +::::{note} +If you’re using the Elastic APM Java agent, log correlation is enabled by default starting in version 1.30.0. In previous versions, log correlation is off by default, but can be enabled by setting the `enable_log_correlation` config to `true`. +:::: + + + +## Step 2: Configure Filebeat [setup-step-2] + +:::::::{tab-set} + +::::::{tab-item} Log file +1. Follow the [Filebeat quick start](beats://docs/reference/filebeat/filebeat-installation-configuration.md) +2. Add the following configuration to your `filebeat.yaml` file. + +For Filebeat 7.16+ + +```yaml +filebeat.inputs: +- type: filestream <1> + paths: /path/to/logs.json + parsers: + - ndjson: + overwrite_keys: true <2> + add_error_key: true <3> + expand_keys: true <4> + +processors: <5> + - add_host_metadata: ~ + - add_cloud_metadata: ~ + - add_docker_metadata: ~ + - add_kubernetes_metadata: ~ +``` + +1. Use the filestream input to read lines from active log files. +2. Values from the decoded JSON object overwrite the fields that {{filebeat}} normally adds (type, source, offset, etc.) in case of conflicts. +3. {{filebeat}} adds an "error.message" and "error.type: json" key in case of JSON unmarshalling errors. +4. {{filebeat}} will recursively de-dot keys in the decoded JSON, and expand them into a hierarchical object structure. +5. Processors enhance your data. See [processors](beats://docs/reference/filebeat/filtering-enhancing-data.md) to learn more. + + +For Filebeat < 7.16 + +```yaml +filebeat.inputs: +- type: log + paths: /path/to/logs.json + json.keys_under_root: true + json.overwrite_keys: true + json.add_error_key: true + json.expand_keys: true + +processors: +- add_host_metadata: ~ +- add_cloud_metadata: ~ +- add_docker_metadata: ~ +- add_kubernetes_metadata: ~ +``` +:::::: + +::::::{tab-item} Kubernetes +1. Make sure your application logs to stdout/stderr. +2. Follow the [Run Filebeat on Kubernetes](beats://docs/reference/filebeat/running-on-kubernetes.md) guide. +3. Enable [hints-based autodiscover](beats://docs/reference/filebeat/configuration-autodiscover-hints.md) (uncomment the corresponding section in `filebeat-kubernetes.yaml`). +4. Add these annotations to your pods that log using ECS loggers. This will make sure the logs are parsed appropriately. + +```yaml +annotations: + co.elastic.logs/json.overwrite_keys: true <1> + co.elastic.logs/json.add_error_key: true <2> + co.elastic.logs/json.expand_keys: true <3> +``` + +1. Values from the decoded JSON object overwrite the fields that {{filebeat}} normally adds (type, source, offset, etc.) in case of conflicts. +2. {{filebeat}} adds an "error.message" and "error.type: json" key in case of JSON unmarshalling errors. +3. {{filebeat}} will recursively de-dot keys in the decoded JSON, and expand them into a hierarchical object structure. +:::::: + +::::::{tab-item} Docker +1. Make sure your application logs to stdout/stderr. +2. Follow the [Run Filebeat on Docker](beats://docs/reference/filebeat/running-on-docker.md) guide. +3. Enable [hints-based autodiscover](beats://docs/reference/filebeat/configuration-autodiscover-hints.md). +4. Add these labels to your containers that log using ECS loggers. This will make sure the logs are parsed appropriately. + +```yaml +labels: + co.elastic.logs/json.overwrite_keys: true <1> + co.elastic.logs/json.add_error_key: true <2> + co.elastic.logs/json.expand_keys: true <3> +``` + +1. Values from the decoded JSON object overwrite the fields that {{filebeat}} normally adds (type, source, offset, etc.) in case of conflicts. +2. {{filebeat}} adds an "error.message" and "error.type: json" key in case of JSON unmarshalling errors. +3. {{filebeat}} will recursively de-dot keys in the decoded JSON, and expand them into a hierarchical object structure. +:::::: + +::::::: +For more information, see the [Filebeat reference](beats://docs/reference/filebeat/configuring-howto-filebeat.md). + + +### When `stackTraceAsArray` is enabled [setup-stack-trace-as-array] + +Filebeat can normally only decode JSON if there is one JSON object per line. When `stackTraceAsArray` is enabled, there will be a new line for each stack trace element which improves readability. But when combining the multiline settings with a `decode_json_fields` we can also handle multi-line JSON: + +```yaml +filebeat.inputs: + - type: log + paths: /path/to/logs.json + multiline.pattern: '^{' + multiline.negate: true + multiline.match: after +processors: + - decode_json_fields: + fields: message + target: "" + overwrite_keys: true + # flattens the array to a single string + - script: + when: + has_fields: ['error.stack_trace'] + lang: javascript + id: my_filter + source: > + function process(event) { + event.Put("error.stack_trace", event.Get("error.stack_trace").join("\n")); + } +``` diff --git a/docs/reference/toc.yml b/docs/reference/toc.yml new file mode 100644 index 00000000..c7ceed8a --- /dev/null +++ b/docs/reference/toc.yml @@ -0,0 +1,4 @@ +toc: + - file: index.md + - file: setup.md + - file: _structured_logging_with_log4j2.md \ No newline at end of file diff --git a/docs/setup.asciidoc b/docs/setup.asciidoc deleted file mode 100644 index d84cd5e8..00000000 --- a/docs/setup.asciidoc +++ /dev/null @@ -1,77 +0,0 @@ -[[setup]] -== Get started - -include::./tab-widgets/code.asciidoc[] - -[float] -[[setup-step-1]] -=== Step 1: Configure application logging - -If you are using the Elastic APM Java agent, the easiest way to transform your logs into ECS-compatible JSON format is through the -{apm-java-ref}/config-logging.html#config-log-ecs-reformatting[`log_ecs_reformatting`] configuration option. -By only setting this option, the Java agent will automatically import the correct ECS-logging library and configure your logging -framework to use it instead (`OVERRIDE`/`REPLACE`) or in addition to (`SHADE`) your current configuration. No other changes required! -Make sure to check out other {apm-java-ref}/config-logging.html[Logging configuration options] to unlock the full potential of this option. - -Otherwise, follow the steps below to manually apply ECS-formatting through your logging framework configuration. -The following logging frameworks are supported: - -* Logback (default for Spring Boot) -* Log4j2 -* Log4j -* `java.util.logging` (JUL) -* JBoss Log Manager - -[float] -==== Add the dependency - -include::./tab-widgets/add-dependency-widget.asciidoc[] - -[float] -==== Use the ECS encoder/formatter/layout - -include::./tab-widgets/ecs-encoder-widget.asciidoc[] - -NOTE: If you're using the Elastic APM Java agent, -log correlation is enabled by default starting in version 1.30.0. -In previous versions, log correlation is off by default, but can be enabled by setting -the `enable_log_correlation` config to `true`. - -[float] -[[setup-step-2]] -=== Step 2: Configure Filebeat - -include::{ecs-repo-dir}/setup.asciidoc[tag=configure-filebeat] - -[float] -[[setup-stack-trace-as-array]] -==== When `stackTraceAsArray` is enabled - -Filebeat can normally only decode JSON if there is one JSON object per line. -When `stackTraceAsArray` is enabled, there will be a new line for each stack trace element which improves readability. -But when combining the multiline settings with a `decode_json_fields` we can also handle multi-line JSON: - -[source,yml] ----- -filebeat.inputs: - - type: log - paths: /path/to/logs.json - multiline.pattern: '^{' - multiline.negate: true - multiline.match: after -processors: - - decode_json_fields: - fields: message - target: "" - overwrite_keys: true - # flattens the array to a single string - - script: - when: - has_fields: ['error.stack_trace'] - lang: javascript - id: my_filter - source: > - function process(event) { - event.Put("error.stack_trace", event.Get("error.stack_trace").join("\n")); - } ----- diff --git a/docs/structured-logging-log4j2.asciidoc b/docs/structured-logging-log4j2.asciidoc deleted file mode 100644 index cdedddd4..00000000 --- a/docs/structured-logging-log4j2.asciidoc +++ /dev/null @@ -1,72 +0,0 @@ -[structured-logging-log4j2] -== Structured logging with log4j2 - -By leveraging log4j2's `MapMessage` or even by implementing your own `MultiformatMessage` with JSON support, -you can add additional fields to the resulting JSON. - -Example: - -[source,java] ----- -logger.info(new StringMapMessage() - .with("message", "Hello World!") - .with("foo", "bar")); ----- - -If Jackson is on the classpath, you can also use an `ObjectMessage` to add a custom object the resulting JSON. - -[source,java] ----- -logger.info(new ObjectMessage(myObject)); ----- - -The `myObject` variable refers to a custom object which can be serialized by a Jackson `ObjectMapper`. - -Using either will merge the object at the top-level (not nested under `message`) of the log event if it is a JSON object. -If it's a string, number boolean, or array, it will be converted into a string and added as the `message` property. -This conversion avoids mapping conflicts as `message` is typed as a string in the Elasticsearch mapping. - -[float] -=== Tips - -We recommend using existing {ecs-ref}/ecs-field-reference.html[ECS fields]. - -If there is no appropriate ECS field, -consider prefixing your fields with `labels.`, as in `labels.foo`, for simple key/value pairs. -For nested structures, consider prefixing with `custom.`. This approach protects against conflicts in case ECS later adds the same fields but with a different mapping. - -[float] -=== Gotchas - -A common pitfall is how dots in field names are handled in Elasticsearch and how they affect the mapping. -In recent Elasticsearch versions, the following JSON structures would result in the same index mapping: - -[source,json] ----- -{ - "foo.bar": "baz" -} ----- - -[source,json] ----- -{ - "foo": { - "bar": "baz" - } -} ----- - -The property `foo` would be mapped to the {ref}/object.html[Object datatype]. - -This means that you can't index a document where `foo` would be a different datatype, as in shown in the following example: - -[source,json] ----- -{ - "foo": "bar" -} ----- - -In that example, `foo` is a string. -Trying to index that document results in an error because the data type of `foo` can't be object and string at the same time. \ No newline at end of file diff --git a/docs/tab-widgets/add-dependency-widget.asciidoc b/docs/tab-widgets/add-dependency-widget.asciidoc deleted file mode 100644 index 8e620ced..00000000 --- a/docs/tab-widgets/add-dependency-widget.asciidoc +++ /dev/null @@ -1,94 +0,0 @@ -++++ -
-
- - - - - -
-
-++++ - -include::add-dependency.asciidoc[tag=logback] - -++++ -
- - - - -
-++++ \ No newline at end of file diff --git a/docs/tab-widgets/add-dependency.asciidoc b/docs/tab-widgets/add-dependency.asciidoc deleted file mode 100644 index 292820ba..00000000 --- a/docs/tab-widgets/add-dependency.asciidoc +++ /dev/null @@ -1,107 +0,0 @@ -// tag::logback[] -The minimum required logback version is 1.1. - -Download the latest version of Elastic logging: https://search.maven.org/search?q=g:co.elastic.logging%20AND%20a:logback-ecs-encoder[image:https://img.shields.io/maven-central/v/co.elastic.logging/logback-ecs-encoder.svg[Maven Central]] - -Add a dependency to your application: -[source,xml] ----- - - co.elastic.logging - logback-ecs-encoder - ${ecs-logging-java.version} - ----- - -NOTE: If you are not using a dependency management tool, like maven, you have to manually add both -`logback-ecs-encoder` and `ecs-logging-core` jars to the classpath. -For example to the `$CATALINA_HOME/lib` directory. -Other than that, there are no required dependencies. -// end::logback[] - -// tag::log4j2[] -The minimum required log4j2 version is 2.6. - -Download the latest version of Elastic logging: https://search.maven.org/search?q=g:co.elastic.logging%20AND%20a:log4j2-ecs-layout:[image:https://img.shields.io/maven-central/v/co.elastic.logging/log4j2-ecs-layout.svg[Maven Central]] - -Add a dependency to your application: -[source,xml] ----- - - co.elastic.logging - log4j2-ecs-layout - ${ecs-logging-java.version} - ----- - -NOTE: If you are not using a dependency management tool, like maven, you have to manually add both -`log4j2-ecs-layout` and `ecs-logging-core` jars to the classpath. -For example, to the `$CATALINA_HOME/lib` directory. -Other than that, there are no required dependencies. -// end::log4j2[] - -// tag::log4j[] -The minimum required log4j version is 1.2.4. - -Download the latest version of Elastic logging: https://search.maven.org/search?q=g:co.elastic.logging%20AND%20a:log4j-ecs-layout[image:https://img.shields.io/maven-central/v/co.elastic.logging/log4j-ecs-layout.svg[Maven Central]] - -Add a dependency to your application: - -[source,xml] ----- - - co.elastic.logging - log4j-ecs-layout - ${ecs-logging-java.version} - ----- - -NOTE: If you are not using a dependency management tool, like maven, you have to manually add both -`log4j-ecs-layout` and `ecs-logging-core` jars to the classpath. -For example, to the `$CATALINA_HOME/lib` directory. -Other than that, there are no required dependencies. -// end::log4j[] - -// tag::jul[] -A formatter for JUL (`java.util.logging`) which produces ECS-compatible records. -Useful for applications that use JUL as primary logging framework, like Apache Tomcat. - -Download the latest version of Elastic logging: https://search.maven.org/search?q=g:co.elastic.logging%20AND%20a:jul-ecs-formatter[image:https://img.shields.io/maven-central/v/co.elastic.logging/jul-ecs-formatter.svg[Maven Central]] - -Add a dependency to your application: -[source,xml] ----- - - co.elastic.logging - jul-ecs-formatter - ${ecs-logging-java.version} - ----- - -NOTE: If you are not using a dependency management tool, like maven, you have to manually add both -`jul-ecs-formatter` and `ecs-logging-core` jars to the classpath. -For example, to the `$CATALINA_HOME/lib` directory. -Other than that, there are no required dependencies. - -// end::jul[] - -// tag::jboss[] -A formatter for JBoss Log Manager which produces ECS-compatible records. -Useful for applications that use JBoss Log Manager as their primary logging framework, like WildFly. - -Download the latest version of Elastic logging: https://search.maven.org/search?q=g:co.elastic.logging%20AND%20a:jboss-logmanager-ecs-formatter[image:https://img.shields.io/maven-central/v/co.elastic.logging/jboss-logmanager-ecs-formatter.svg[Maven Central]] - -Add a dependency to your application: -[source,xml] ----- - - co.elastic.logging - jboss-logmanager-ecs-formatter - ${ecs-logging-java.version} - ----- - -NOTE: If you are not using a dependency management tool, like maven, you have to manually add both -`jboss-logmanager-ecs-formatter` and `ecs-logging-core` jars to the classpath. -Other than that, there are no required dependencies. -// end::jboss[] diff --git a/docs/tab-widgets/code.asciidoc b/docs/tab-widgets/code.asciidoc deleted file mode 100644 index 6a30cf55..00000000 --- a/docs/tab-widgets/code.asciidoc +++ /dev/null @@ -1,166 +0,0 @@ -// Defining styles and script here for simplicity. -++++ - - - -++++ \ No newline at end of file diff --git a/docs/tab-widgets/ecs-encoder-widget.asciidoc b/docs/tab-widgets/ecs-encoder-widget.asciidoc deleted file mode 100644 index a4206a81..00000000 --- a/docs/tab-widgets/ecs-encoder-widget.asciidoc +++ /dev/null @@ -1,94 +0,0 @@ -++++ -
-
- - - - - -
-
-++++ - -include::ecs-encoder.asciidoc[tag=logback] - -++++ -
- - - - -
-++++ \ No newline at end of file diff --git a/docs/tab-widgets/ecs-encoder.asciidoc b/docs/tab-widgets/ecs-encoder.asciidoc deleted file mode 100644 index a53cf9b5..00000000 --- a/docs/tab-widgets/ecs-encoder.asciidoc +++ /dev/null @@ -1,436 +0,0 @@ -// tag::logback[] -**Spring Boot applications** - -In `src/main/resources/logback-spring.xml`: - -[source,xml] ----- - - - - - - - - - - - - - - - ----- - -You also need to configure the following properties to your `application.properties`: - -[source,properties] ----- -spring.application.name=my-application -# for Spring Boot 2.2.x+ -logging.file.name=/path/to/my-application.log -# for older Spring Boot versions -logging.file=/path/to/my-application.log ----- - -**Other applications** - -All you have to do is to use the `co.elastic.logging.logback.EcsEncoder` instead of the default pattern encoder in `logback.xml` - -[source,xml] ----- - - my-application - my-application-version - my-application-environment - my-application-cluster-node - ----- - -**Encoder Parameters** - -|=== -|Parameter name |Type |Default| Description - -|`serviceName` -|String -| -|Sets the `service.name` field so you can filter your logs by a particular service name - -|`serviceVersion` -|String -| -|Sets the `service.version` field so you can filter your logs by a particular service version - -|`serviceEnvironment` -|String -| -|Sets the `service.environment` field so you can filter your logs by a particular service environment - -|`serviceNodeName` -|String -| -|Sets the `service.node.name` field so you can filter your logs by a particular node of your clustered service - -|`eventDataset` -|String -|`${serviceName}` -|Sets the `event.dataset` field used by the machine learning job of the Logs app to look for anomalies in the log rate. - -|`includeMarkers` -|boolean -|`false` -|Log https://logging.apache.org/log4j/2.0/manual/markers.html[Markers] as {ecs-ref}/ecs-base.html[`tags`] - -|`stackTraceAsArray` -|boolean -|`false` -|Serializes the {ecs-ref}/ecs-error.html[`error.stack_trace`] as a JSON array where each element is in a new line to improve readability. -Note that this requires a slightly more complex <>. - -|`includeOrigin` -|boolean -|`false` -|If `true`, adds the {ecs-ref}/ecs-log.html[`log.origin.file.name`], - {ecs-ref}/ecs-log.html[`log.origin.file.line`] and {ecs-ref}/ecs-log.html[`log.origin.function`] fields. - Note that you also have to set `true` on your appenders if you are using the async ones. -|=== - -To include any custom field in the output, use following syntax: - -[source,xml] ----- - - key1 - value1 - - - key2 - value2 - ----- - -// end::logback[] - -// tag::log4j2[] -Instead of the usual ``, use ``. -For example: - -[source,xml] ----- - - - - - - - - - - - - - - - - - ----- - -**Layout Parameters** - -|=== -|Parameter name |Type |Default |Description - -|`serviceName` -|String -| -|Sets the `service.name` field so you can filter your logs by a particular service name - -|`serviceVersion` -|String -| -|Sets the `service.version` field so you can filter your logs by a particular service version - -|`serviceEnvironment` -|String -| -|Sets the `service.environment` field so you can filter your logs by a particular service environment - -|`serviceNodeName` -|String -| -|Sets the `service.node.name` field so you can filter your logs by a particular node of your clustered service - -|`eventDataset` -|String -|`${serviceName}` -|Sets the `event.dataset` field used by the machine learning job of the Logs app to look for anomalies in the log rate. - -|`includeMarkers` -|boolean -|`false` -|Log https://logging.apache.org/log4j/2.0/manual/markers.html[Markers] as {ecs-ref}/ecs-base.html[`tags`] - -|`stackTraceAsArray` -|boolean -|`false` -|Serializes the {ecs-ref}/ecs-error.html[`error.stack_trace`] as a JSON array where each element is in a new line to improve readability. - Note that this requires a slightly more complex <>. - -|`includeOrigin` -|boolean -|`false` -|If `true`, adds the {ecs-ref}/ecs-log.html[`log.origin.file.name`], - {ecs-ref}/ecs-log.html[`log.origin.file.line`] and {ecs-ref}/ecs-log.html[`log.origin.function`] fields. - Note that you also have to set `includeLocation="true"` on your loggers and appenders if you are using the async ones. -|=== - -To include any custom field in the output, use following syntax: - -[source,xml] ----- - - - - ----- - -Custom fields are included in the order they are declared. The values support https://logging.apache.org/log4j/2.x/manual/lookups.html[lookups]. -This means that the `KeyValuePair` setting can be utilized to dynamically set predefined fields as well: - -[source,xml] ----- - - - - ----- - -NOTE: The log4j2 `EcsLayout` does not allocate any memory (unless the log event contains an `Exception`) to reduce GC pressure. -This is achieved by manually serializing JSON so that no intermediate JSON or map representation of a log event is needed. -// end::log4j2[] - -// tag::log4j[] -Instead of the usual layout class `"org.apache.log4j.PatternLayout"`, use `"co.elastic.logging.log4j.EcsLayout"`. -For example: - -[source,xml] ----- - - - - - - - - - - - - - - - - - - - - - - - ----- - - -**Layout Parameters** - -|=== -|Parameter name |Type |Default |Description - -|`serviceName` -|String -| -|Sets the `service.name` field so you can filter your logs by a particular service name - -|`serviceVersion` -|String -| -|Sets the `service.version` field so you can filter your logs by a particular service version - -|`serviceEnvironment` -|String -| -|Sets the `service.environment` field so you can filter your logs by a particular service environment - -|`serviceNodeName` -|String -| -|Sets the `service.node.name` field so you can filter your logs by a particular node of your clustered service - -|`eventDataset` -|String -|`${serviceName}` -|Sets the `event.dataset` field used by the machine learning job of the Logs app to look for anomalies in the log rate. - -|`stackTraceAsArray` -|boolean -|`false` -|Serializes the {ecs-ref}/ecs-error.html[`error.stack_trace`] as a JSON array where each element is in a new line to improve readability. -Note that this requires a slightly more complex <>. - -|`includeOrigin` -|boolean -|`false` -|If `true`, adds the {ecs-ref}/ecs-log.html[`log.origin.file.name`], -{ecs-ref}/ecs-log.html[`log.origin.file.line`] and {ecs-ref}/ecs-log.html[`log.origin.function`] fields. -Note that you also have to set `` if you are using `AsyncAppender`. -|=== - -To include any custom field in the output, use following syntax: - -[source,xml] ----- - - - - ----- - -Custom fields are included in the order they are declared. -// end::log4j[] - -// tag::jul[] -Specify `co.elastic.logging.jul.EcsFormatter` as `formatter` for the required log handler. - -For example, in `$CATALINA_HOME/conf/logging.properties`: - -[source, properties] ----- -java.util.logging.ConsoleHandler.level = FINE -java.util.logging.ConsoleHandler.formatter = co.elastic.logging.jul.EcsFormatter -co.elastic.logging.jul.EcsFormatter.serviceName=my-app -co.elastic.logging.jul.EcsFormatter.serviceVersion=my-app-version -co.elastic.logging.jul.EcsFormatter.serviceEnvironment=my-app-environment -co.elastic.logging.jul.EcsFormatter.serviceNodeName=my-app-cluster-node ----- - -**Layout Parameters** - -|=== -|Parameter name |Type |Default |Description - -|`serviceName` -|String -| -|Sets the `service.name` field so you can filter your logs by a particular service name - -|`serviceVersion` -|String -| -|Sets the `service.version` field so you can filter your logs by a particular service version - -|`serviceEnvironment` -|String -| -|Sets the `service.environment` field so you can filter your logs by a particular service environment - -|`serviceNodeName` -|String -| -|Sets the `service.node.name` field so you can filter your logs by a particular node of your clustered service - -|`eventDataset` -|String -|`${serviceName}` -|Sets the `event.dataset` field used by the machine learning job of the Logs app to look for anomalies in the log rate. - -|`stackTraceAsArray` -|boolean -|`false` -|Serializes the {ecs-ref}/ecs-error.html[`error.stack_trace`] as a JSON array where each element is in a new line to improve readability. Note that this requires a slightly more complex [Filebeat configuration](../README.md#when-stacktraceasarray-is-enabled). - -|`includeOrigin` -|boolean -|`false` -|If `true`, adds the {ecs-ref}/ecs-log.html[`log.origin.file.name`], - {ecs-ref}/ecs-log.html[`log.origin.file.line`] and {ecs-ref}/ecs-log.html[`log.origin.function`] fields. - Note that JUL does not stores line number and `log.origin.file.line` will have '1' value. - -|`additionalFields` -|String -| -|Adds additional static fields to all log events. - The fields are specified as comma-separated key-value pairs. - Example: `co.elastic.logging.jul.EcsFormatter.additionalFields=key1=value1,key2=value2`. -|=== -// end::jul[] - -// tag::jboss[] -Specify `co.elastic.logging.jboss.logmanager.EcsFormatter` as `formatter` for the required log handler. - -For example, with Wildfly, create a `jboss-logmanager-ecs-formatter` module: - -[source,bash] ----- -$WILDFLY_HOME/bin/jboss-cli.sh -c 'module add --name=co.elastic.logging.jboss-logmanager-ecs-formatter --resources=jboss-logmanager-ecs-formatter-${ecs-logging-java.version}.jar:/tmp/ecs-logging-core-${ecs-logging-java.version}.jar --dependencies=org.jboss.logmanager' ----- - -Add the formatter to a handler in the logging subsystem: - -[source,bash] ----- -$WILDFLY_HOME/bin/jboss-cli.sh -c '/subsystem=logging/custom-formatter=ECS:add(module=co.elastic.logging.jboss-logmanager-ecs-formatter, -class=co.elastic.logging.jboss.logmanager.EcsFormatter, properties={serviceName=my-app,serviceVersion=my-app-version,serviceEnvironment=my-app-environment,serviceNodeName=my-app-cluster-node}),\ - /subsystem=logging/console-handler=CONSOLE:write-attribute(name=named-formatter,value=ECS)' ----- - -**Layout Parameters** - -|=== -|Parameter name |Type |Default |Description - -|`serviceName` -|String -| -|Sets the `service.name` field so you can filter your logs by a particular service name - -|`serviceVersion` -|String -| -|Sets the `service.version` field so you can filter your logs by a particular service version - -|`serviceEnvironment` -|String -| -|Sets the `service.environment` field so you can filter your logs by a particular service environment - -|`serviceNodeName` -|String -| -|Sets the `service.node.name` field so you can filter your logs by a particular node of your clustered service - -|`eventDataset` -|String -|`${serviceName}` -|Sets the `event.dataset` field used by the machine learning job of the Logs app to look for anomalies in the log rate. - -|`stackTraceAsArray` -|boolean -|`false` -|Serializes the {ecs-ref}/ecs-error.html[`error.stack_trace`] as a JSON array where each element is in a new line to improve readability. Note that this requires a slightly more complex <>. - -|`includeOrigin` -|boolean -|`false` -|If `true`, adds the {ecs-ref}/ecs-log.html[`log.origin.file.name`], - {ecs-ref}/ecs-log.html[`log.origin.file.line`] and {ecs-ref}/ecs-log.html[`log.origin.function`] fields. - -|`additionalFields` -|String -| -|Adds additional static fields to all log events. - The fields are specified as comma-separated key-value pairs. - Example: `additionalFields=key1=value1,key2=value2`. -|=== -// end::jboss[]