Skip to content

Commit 07a5c4e

Browse files
schwzrschwzr
committed
added first draft of logging documentation
1 parent 0c0caf9 commit 07a5c4e

File tree

2 files changed

+192
-0
lines changed

2 files changed

+192
-0
lines changed

‎docs/src/operations/v2.0.0-RC2/bpe/logging.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: Logging
3+
icon: config
4+
---
5+
6+
## 1. Introduction
7+
The DSF BPE executes distributed workflows and provides three logging channels: **Standard Logs**,
8+
a **Data Logger** for introspection purposes, and **BPMN Debug Logs** for process plugin developers.
9+
10+
---
11+
12+
## Standard Logging
13+
14+
| Purpose | Property Key | Environment Variable | Default |
15+
|---------|--------------|----------------------|---------|
16+
| External Log4j2 config | [`dev.dsf.log.config`](../bpe/configuration.md#dev-dsf-log-config) | [`DEV_DSF_LOG_CONFIG`](../bpe/configuration.md#dev-dsf-log-config) | `conf/log4j2.xml` |
17+
| Enable stderr logging | [`dev.dsf.log.console.err.enabled`](../bpe/configuration.md#dev-dsf-log-console-err-enabled) | [`DEV_DSF_LOG_CONSOLE_ERR_ENABLED`](../bpe/configuration.md#dev-dsf-log-console-err-enabled) | `false` |
18+
| Level for stderr | [`dev.dsf.log.console.err.level`](../bpe/configuration.md#dev-dsf-log-console-err-level) | [`DEV_DSF_LOG_CONSOLE_ERR_LEVEL`](../bpe/configuration.md#dev-dsf-log-console-err-level) | `INFO` |
19+
| Style for stderr | [`dev.dsf.log.console.err.style`](../bpe/configuration.md#dev-dsf-log-console-err-style) | [`DEV_DSF_LOG_CONSOLE_ERR_STYLE`](../bpe/configuration.md#dev-dsf-log-console-err-style) | `TEXT_COLOR` |
20+
| Enable stdout logging | [`dev.dsf.log.console.out.enabled`](../bpe/configuration.md#dev-dsf-log-console-out-enabled) | [`DEV_DSF_LOG_CONSOLE_OUT_ENABLED`](../bpe/configuration.md#dev-dsf-log-console-out-enabled) | `true` |
21+
| Level for stdout | [`dev.dsf.log.console.out.level`](../bpe/configuration.md#dev-dsf-log-console-out-level) | [`DEV_DSF_LOG_CONSOLE_OUT_LEVEL`](../bpe/configuration.md#dev-dsf-log-console-out-level) | `INFO` |
22+
| Style for stdout | [`dev.dsf.log.console.out.style`](../bpe/configuration.md#dev-dsf-log-console-out-style) | [`DEV_DSF_LOG_CONSOLE_OUT_STYLE`](../bpe/configuration.md#dev-dsf-log-console-out-style) | `TEXT_COLOR` |
23+
| Enable file logging | [`dev.dsf.log.file.enabled`](../bpe/configuration.md#dev-dsf-log-file-enabled) | [`DEV_DSF_LOG_FILE_ENABLED`](../bpe/configuration.md#dev-dsf-log-file-enabled) | `true` |
24+
| File log level | [`dev.dsf.log.file.level`](../bpe/configuration.md#dev-dsf-log-file-level) | [`DEV_DSF_LOG_FILE_LEVEL`](../bpe/configuration.md#dev-dsf-log-file-level) | `DEBUG` |
25+
| File log style | [`dev.dsf.log.file.style`](../bpe/configuration.md#dev-dsf-log-file-style) | [`DEV_DSF_LOG_FILE_STYLE`](../bpe/configuration.md#dev-dsf-log-file-style) | `TEXT_MDC` |
26+
27+
---
28+
29+
## Data Logger
30+
31+
| Purpose | Property Key | Environment Variable | Default |
32+
|---------|--------------|----------------------|---------|
33+
| Enable data log file | [`dev.dsf.log.data.file.enabled`](../bpe/configuration.md#dev-dsf-log-data-file-enabled) | [`DEV_DSF_LOG_DATA_FILE_ENABLED`](../bpe/configuration.md#dev-dsf-log-data-file-enabled) | `false` |
34+
| Data file style | [`dev.dsf.log.data.file.style`](../bpe/configuration.md#dev-dsf-log-data-file-style) | [`DEV_DSF_LOG_DATA_FILE_STYLE`](../bpe/configuration.md#dev-dsf-log-data-file-style) | `TEXT` |
35+
| Enable data logs on stdout | [`dev.dsf.log.data.console.out.enabled`](../bpe/configuration.md#dev-dsf-log-data-console-out-enabled) | [`DEV_DSF_LOG_DATA_CONSOLE_OUT_ENABLED`](../bpe/configuration.md#dev-dsf-log-data-console-out-enabled) | `false` |
36+
| Style for stdout | [`dev.dsf.log.data.console.out.style`](../bpe/configuration.md#dev-dsf-log-data-console-out-style) | [`DEV_DSF_LOG_DATA_CONSOLE_OUT_STYLE`](../bpe/configuration.md#dev-dsf-log-data-console-out-style) | `TEXT` |
37+
| Enable data logs on stderr | [`dev.dsf.log.data.console.err.enabled`](../bpe/configuration.md#dev-dsf-log-data-console-err-enabled) | [`DEV_DSF_LOG_DATA_CONSOLE_ERR_ENABLED`](../bpe/configuration.md#dev-dsf-log-data-console-err-enabled) | `false` |
38+
| Style for stderr | [`dev.dsf.log.data.console.err.style`](../bpe/configuration.md#dev-dsf-log-data-console-err-style) | [`DEV_DSF_LOG_DATA_CONSOLE_ERR_STYLE`](../bpe/configuration.md#dev-dsf-log-data-console-err-style) | `TEXT` |
39+
40+
---
41+
42+
## BPMN Debug Logging
43+
44+
| Purpose | Property Key | Environment Variable | Default |
45+
|---------|--------------|----------------------|---------|
46+
| Log current DSF user | [`dev.dsf.bpe.debug.log.message.currentUser`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-currentuser) | [`DEV_DSF_BPE_DEBUG_LOG_MESSAGE_CURRENTUSER`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-currentuser) | `false` |
47+
| Log SQL statements | [`dev.dsf.bpe.debug.log.message.dbStatement`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-dbstatement) | [`DEV_DSF_BPE_DEBUG_LOG_MESSAGE_DBSTATEMENT`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-dbstatement) | `false` |
48+
| Log activity start | [`dev.dsf.bpe.debug.log.message.onActivityStart`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-onactivitystart) | [`DEV_DSF_BPE_DEBUG_LOG_MESSAGE_ONACTIVITYSTART`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-onactivitystart) | `false` |
49+
| Log activity end | [`dev.dsf.bpe.debug.log.message.onActivityEnd`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-onactivityend) | [`DEV_DSF_BPE_DEBUG_LOG_MESSAGE_ONACTIVITYEND`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-onactivityend) | `false` |
50+
| Log all variables | [`dev.dsf.bpe.debug.log.message.variables`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-variables) | [`DEV_DSF_BPE_DEBUG_LOG_MESSAGE_VARIABLES`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-variables) | `false` |
51+
| Log local variables only | [`dev.dsf.bpe.debug.log.message.variablesLocal`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-variableslocal) | [`DEV_DSF_BPE_DEBUG_LOG_MESSAGE_VARIABLESLOCAL`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-variableslocal) | `false` |
52+
| Log webservice requests | [`dev.dsf.bpe.debug.log.message.webserviceRequest`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-webservicerequest) | [`DEV_DSF_BPE_DEBUG_LOG_MESSAGE_WEBSERVICEREQUEST`](../bpe/configuration.md#dev-dsf-bpe-debug-log-message-webservicerequest) | `false` |
53+
54+
55+
## Logging Styles
56+
The DSF logging system supports multiple output styles that can be selected independently for each logging channel (console, file, audit, data).
57+
Every logger exposes a *.style property and a corresponding environment variable.
58+
59+
### Text-Based Logging Styles
60+
#### TEXT
61+
62+
Plain, unformatted text output (default for console output, used before DSF 2).
63+
64+
Use when:
65+
- You want minimal overhead and simple logging.
66+
- Logs are read directly on the system.
67+
68+
Avoid when:
69+
- A log aggregation system is used.
70+
71+
#### TEXT_MDC
72+
73+
Plain text with MDC (Mapped Diagnostic Context) fields, such as:
74+
75+
- correlationId
76+
- processInstanceId
77+
- user
78+
- requestId
79+
80+
Recommended for:
81+
- Production file logs
82+
- Debugging distributed workflows with correlation IDs
83+
84+
Not ideal for:
85+
- A log aggregation system is used.
86+
87+
#### TEXT_COLOR and TEXT_COLOR_MDC
88+
89+
ANSI-colored text output for terminals.
90+
91+
Recommended for:
92+
- Local development
93+
- Docker logs viewed directly with docker logs
94+
- Developers who want fast visual distinction between INFO/WARN/ERROR
95+
96+
Avoid for:
97+
- Log ingestion systems
98+
- Consoles without ANSI escape code support
99+
100+
101+
### JSON-Based Logging Styles
102+
We support the structured logging formats `JSON_LOGSTASH`, `JSON_ECS`(Elastic Common Schema), `JSON_GELF`(Graylog Extended Log Format), and `JSON_GCP` (Google Cloud Platform Logging). They all include Mapped Diagnostic Context information (e.g., process names, ids, ...) and should be used in combination with your log aggreation system of your choice.

‎docs/src/operations/v2.0.0-RC2/fhir/logging.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: Logging
3+
icon: config
4+
---
5+
6+
## Introduction
7+
The DSF FHIR Server provides two logging mechanisms: a **Standard Application Logger** and a dedicated
8+
**Audit Logger** for compliance-relevant access events. DSF 2.0.0 introduces unified `*.enabled` flags,
9+
extended output styles, and improved environment variable support.
10+
11+
12+
13+
## Audit Logging
14+
15+
16+
17+
| Purpose | Property Key | Environment Variable | Default |
18+
|---------|--------------|----------------------|---------|
19+
| Enable audit logs on stderr | [`dev.dsf.log.audit.console.err.enabled`](./configuration.md#dev-dsf-log-audit-console-err-enabled) | [`DEV_DSF_LOG_AUDIT_CONSOLE_ERR_ENABLED`](./configuration.md#dev-dsf-log-audit-console-err-enabled) | `false` |
20+
| Style for stderr | [`dev.dsf.log.audit.console.err.style`](./configuration.md#dev-dsf-log-audit-console-err-style) | [`DEV_DSF_LOG_AUDIT_CONSOLE_ERR_STYLE`](./configuration.md#dev-dsf-log-audit-console-err-style) | `TEXT` |
21+
| Enable audit logs on stdout | [`dev.dsf.log.audit.console.out.enabled`](./configuration.md#dev-dsf-log-audit-console-out-enabled) | [`DEV_DSF_LOG_AUDIT_CONSOLE_OUT_ENABLED`](./configuration.md#dev-dsf-log-audit-console-out-enabled) | `false` |
22+
| Style for stdout | [`dev.dsf.log.audit.console.out.style`](./configuration.md#dev-dsf-log-audit-console-out-style) | [`DEV_DSF_LOG_AUDIT_CONSOLE_OUT_STYLE`](./configuration.md#dev-dsf-log-audit-console-out-style) | `TEXT` |
23+
| Enable audit log file | [`dev.dsf.log.audit.file.enabled`](./configuration.md#dev-dsf-log-audit-file-enabled) | [`DEV_DSF_LOG_AUDIT_FILE_ENABLED`](./configuration.md#dev-dsf-log-audit-file-enabled) | `true` |
24+
| Style for audit log file | [`dev.dsf.log.audit.file.style`](./configuration.md#dev-dsf-log-audit-file-style) | [`DEV_DSF_LOG_AUDIT_FILE_STYLE`](./configuration.md#dev-dsf-log-audit-file-style) | `TEXT_MDC` |
25+
26+
---
27+
28+
## Standard Application Logging
29+
30+
| Purpose | Property Key | Environment Variable | Default |
31+
|---------|--------------|----------------------|---------|
32+
| External Log4j2 config | [`dev.dsf.log.config`](./configuration.md#dev-dsf-log-config) | [`DEV_DSF_LOG_CONFIG`](./configuration.md#dev-dsf-log-config) | `conf/log4j2.xml` |
33+
| Enable stderr logging | [`dev.dsf.log.console.err.enabled`](./configuration.md#dev-dsf-log-console-err-enabled) | [`DEV_DSF_LOG_CONSOLE_ERR_ENABLED`](./configuration.md#dev-dsf-log-console-err-enabled) | `false` |
34+
| Level for stderr | [`dev.dsf.log.console.err.level`](./configuration.md#dev-dsf-log-console-err-level) | [`DEV_DSF_LOG_CONSOLE_ERR_LEVEL`](./configuration.md#dev-dsf-log-console-err-level) | `INFO` |
35+
| Style for stderr | [`dev.dsf.log.console.err.style`](./configuration.md#dev-dsf-log-console-err-style) | [`DEV_DSF_LOG_CONSOLE_ERR_STYLE`](./configuration.md#dev-dsf-log-console-err-style) | `TEXT_COLOR` |
36+
| Enable stdout logging | [`dev.dsf.log.console.out.enabled`](./configuration.md#dev-dsf-log-console-out-enabled) | [`DEV_DSF_LOG_CONSOLE_OUT_ENABLED`](./configuration.md#dev-dsf-log-console-out-enabled) | `true` |
37+
| Level for stdout | [`dev.dsf.log.console.out.level`](./configuration.md#dev-dsf-log-console-out-level) | [`DEV_DSF_LOG_CONSOLE_OUT_LEVEL`](./configuration.md#dev-dsf-log-console-out-level) | `INFO` |
38+
| Style for stdout | [`dev.dsf.log.console.out.style`](./configuration.md#dev-dsf-log-console-out-style) | [`DEV_DSF_LOG_CONSOLE_OUT_STYLE`](./configuration.md#dev-dsf-log-console-out-style) | `TEXT_COLOR` |
39+
| Enable file logging | [`dev.dsf.log.file.enabled`](./configuration.md#dev-dsf-log-file-enabled) | [`DEV_DSF_LOG_FILE_ENABLED`](./configuration.md#dev-dsf-log-file-enabled) | `true` |
40+
| File log level | [`dev.dsf.log.file.level`](./configuration.md#dev-dsf-log-file-level) | [`DEV_DSF_LOG_FILE_LEVEL`](./configuration.md#dev-dsf-log-file-level) | `DEBUG` |
41+
| File log style | [`dev.dsf.log.file.style`](./configuration.md#dev-dsf-log-file-style) | [`DEV_DSF_LOG_FILE_STYLE`](./configuration.md#dev-dsf-log-file-style) | `TEXT_MDC` |
42+
43+
## Logging Styles
44+
The DSF logging system supports multiple output styles that can be selected independently for each logging channel (console, file, audit, data).
45+
Every logger exposes a *.style property and a corresponding environment variable.
46+
47+
### Text-Based Logging Styles
48+
#### TEXT
49+
50+
Plain, unformatted text output (default for console output, used before DSF 2).
51+
52+
Use when:
53+
- You want minimal overhead and simple logging.
54+
- Logs are read directly on the system.
55+
56+
Avoid when:
57+
- A log aggregation system is used.
58+
59+
#### TEXT_MDC
60+
61+
Plain text with MDC (Mapped Diagnostic Context) fields, such as:
62+
63+
- correlationId
64+
- processInstanceId
65+
- user
66+
- requestId
67+
68+
Recommended for:
69+
- Production file logs
70+
- Debugging distributed workflows with correlation IDs
71+
72+
Not ideal for:
73+
- A log aggregation system is used.
74+
75+
#### TEXT_COLOR and TEXT_COLOR_MDC
76+
77+
ANSI-colored text output for terminals.
78+
79+
Recommended for:
80+
- Local development
81+
- Docker logs viewed directly with docker logs
82+
- Developers who want fast visual distinction between INFO/WARN/ERROR
83+
84+
Avoid for:
85+
- Log ingestion systems
86+
- Consoles without ANSI escape code support
87+
88+
89+
### JSON-Based Logging Styles
90+
We support the structured logging formats `JSON_LOGSTASH`, `JSON_ECS`(Elastic Common Schema), `JSON_GELF`(Graylog Extended Log Format), and `JSON_GCP` (Google Cloud Platform Logging). They all include Mapped Diagnostic Context information (e.g., process names, ids, ...) and should be used in combination with your log aggreation system of your choice.

0 commit comments

Comments
 (0)