|
| 1 | +# `log4net` instrumentation |
| 2 | + |
| 3 | +> [!IMPORTANT] |
| 4 | +> log4net bridge and trace context injection are experimental features. |
| 5 | +> Both instrumentations can be disabled by setting `OTEL_DOTNET_AUTO_LOGS_LOG4NET_INSTRUMENTATION_ENABLED` to `false`. |
| 6 | +
|
| 7 | +Both bridge and trace context injection are supported for `log4net` in versions >= 2.0.13 && < 4.0.0 |
| 8 | + |
| 9 | +## `log4net` [logs bridge](https://opentelemetry.io/docs/specs/otel/glossary/#log-appender--bridge) |
| 10 | + |
| 11 | +The `log4net` logs bridge is disabled by default. In order to enable it, set `OTEL_DOTNET_AUTO_LOGS_ENABLE_LOG4NET_BRIDGE` to `true`. |
| 12 | +When `log4net` logs bridge is enabled, and `log4net` is configured with at least 1 appender, application logs are exported in OTLP |
| 13 | +format by default to the local instance of OpenTelemetry Collector, in addition to being written into their currently configured destination (e.g. a file). |
| 14 | + |
| 15 | +### `log4net` logging events conversion |
| 16 | + |
| 17 | +`log4net`'s `LoggingEvent`s are converted to OpenTelemetry log records in a following way: |
| 18 | + |
| 19 | +- `TimeStampUtc` is set as a `Timestamp` |
| 20 | +- `Level.Name` is set as a `SeverityText` |
| 21 | +- If formatted strings were used for logging (e.g. by using `InfoFormat` or similar), format string is set as a `Body` |
| 22 | +- Otherwise, `RenderedMessage` is set as a `Body` |
| 23 | +- If formatted strings were used for logging, format arguments are added as attributes, with indexes as their names |
| 24 | +- If formatted strings were used for logging, and `OTEL_DOTNET_AUTO_LOGS_INCLUDE_FORMATTED_MESSAGE` is set, rendered message |
| 25 | +is added as `log4net.rendered_message` attribute |
| 26 | +- `LoggerName` is set as an `InstrumentationScope.Name` |
| 27 | +- `Properties`, apart from builtin properties prefixed with `log4net:`, are added as attributes |
| 28 | +- `Exception` is used to populate the following properties: `exception.type`,`exception.message`,`exception.stacktrace` |
| 29 | +- `Level.Value` is mapped to `SeverityNumber` as outlined in the next section |
| 30 | + |
| 31 | +#### `log4net` level severity mapping |
| 32 | + |
| 33 | +`log4net` levels are mapped to OpenTelemetry severity types according to the following rules based on their numerical values. |
| 34 | + |
| 35 | +Levels with numerical values of: |
| 36 | + |
| 37 | +- Equal to `Level.Fatal` or higher are mapped to `LogRecordSeverity.Fatal` |
| 38 | +- Higher than or equal to `Level.Error` but lower than `Level.Fatal` are mapped to `LogRecordSeverity.Error` |
| 39 | +- Higher than or equal to `Level.Warn` but lower than `Level.Error` are mapped to `LogRecordSeverity.Warn` |
| 40 | +- Higher than or equal to `Level.Info` but lower than `Level.Warn` are mapped to `LogRecordSeverity.Info` |
| 41 | +- Higher than or equal to `Level.Debug` but lower than `Level.Info` are mapped to `LogRecordSeverity.Debug` |
| 42 | +- Lower than `Level.Debug` are mapped to `LogRecordSeverity.Trace` |
| 43 | + |
| 44 | +## `log4net` trace context injection |
| 45 | + |
| 46 | +Following properties are added by default to the collection of logging event's properties: |
| 47 | + |
| 48 | +- `trace_id` |
| 49 | +- `span_id` |
| 50 | +- `trace_flags` |
| 51 | + |
| 52 | +This allows for trace context to be logged into currently configured log destination, e.g. a file. |
| 53 | +In order to use them, pattern needs to be updated. |
| 54 | + |
| 55 | +## Known limitations of `log4net` bridge |
| 56 | + |
| 57 | +In order for the bridge to be added, at least 1 other appender has to be configured. |
| 58 | +Bridge should not be used when appenders are configured for both root and component loggers. |
| 59 | +Enabling a bridge in such scenario would result in bridge being appended to both appender collections, |
| 60 | +and logs duplication. |
| 61 | + |
| 62 | + |
0 commit comments