Skip to content
Permalink
Browse files
Docs for request logging (#12363)
* add docs for request logging

* remove stray character

* Update docs/operations/request-logging.md

Co-authored-by: TSFenwick <tsfenwick@gmail.com>

* Apply suggestions from code review

Co-authored-by: Charles Smith <techdocsmith@gmail.com>

Co-authored-by: TSFenwick <tsfenwick@gmail.com>
Co-authored-by: Charles Smith <techdocsmith@gmail.com>
  • Loading branch information
3 people committed Mar 28, 2022
1 parent f2495a6 commit 9ed7aa33ecaf9e9eab09a7a5f769afcd58209d6a
Show file tree
Hide file tree
Showing 4 changed files with 330 additions and 64 deletions.
@@ -251,16 +251,17 @@ Note that some sensitive information may be logged if these settings are enabled
### Request Logging

All processes that can serve queries can also log the query requests they see. Broker processes can additionally log the SQL requests (both from HTTP and JDBC) they see.
For an example of setting up request logging, see [Request logging](../operations/request-logging.md).

|Property|Description|Default|
|--------|-----------|-------|
|`druid.request.logging.type`|Choices: noop, file, emitter, slf4j, filtered, composing, switching. How to log every query request.|[required to configure request logging]|
|`druid.request.logging.type`|How to log every query request. Choices: `noop`, [`file`](#file-request-logging), [`emitter`](#emitter-request-logging), [`slf4j`](#slf4j-request-logging), [`filtered`](#filtered-request-logging), [`composing`](#composing-request-logging), [`switching`](#switching-request-logging)|`noop` (request logging disabled by default)|

Note that, you can enable sending all the HTTP requests to log by setting "org.apache.druid.jetty.RequestLog" to DEBUG level. See [Logging](../configuration/logging.md)
Note that you can enable sending all the HTTP requests to log by setting `org.apache.druid.jetty.RequestLog` to the `DEBUG` level. See [Logging](../configuration/logging.md) for more information.

#### File Request Logging
#### File request logging

Daily request logs are stored on disk.
The `file` request logger stores daily request logs on disk.

|Property|Description|Default|
|--------|-----------|-------|
@@ -279,24 +280,24 @@ For SQL query request, the `native_query` field is empty. Example
2019-01-14T10:00:00.000Z 127.0.0.1 {"sqlQuery/time":100,"sqlQuery/bytes":600,"success":true,"identity":"user1"} {"query":"SELECT page, COUNT(*) AS Edits FROM wikiticker WHERE __time BETWEEN TIMESTAMP '2015-09-12 00:00:00' AND TIMESTAMP '2015-09-13 00:00:00' GROUP BY page ORDER BY Edits DESC LIMIT 10","context":{"sqlQueryId":"c9d035a0-5ffd-4a79-a865-3ffdadbb5fdd","nativeQueryIds":"[490978e4-f5c7-4cf6-b174-346e63cf8863]"}}
```

#### Emitter Request Logging
#### Emitter request logging

Every request is emitted to some external location.
The `emitter` request logger emits every request to the external location specified in the [emitter](#enabling-metrics) configuration.

|Property|Description|Default|
|--------|-----------|-------|
|`druid.request.logging.feed`|Feed name for requests.|none|

#### SLF4J Request Logging
#### SLF4J request logging

Every request is logged via SLF4J. Native queries are serialized into JSON in the log message regardless of the SLF4J format specification. They will be logged under the class `org.apache.druid.server.log.LoggingRequestLogger`.
The `slf4j` request logger logs every request using SLF4J. It serializes native queries into JSON in the log message regardless of the SLF4J format specification. Requests are logged under the class `org.apache.druid.server.log.LoggingRequestLogger`.

|Property|Description|Default|
|--------|-----------|-------|
|`druid.request.logging.setMDC`|If MDC entries should be set in the log entry. Your logging setup still has to be configured to handle MDC to format this data|false|
|`druid.request.logging.setContextMDC`|If the druid query `context` should be added to the MDC entries. Has no effect unless `setMDC` is `true`|false|
|`druid.request.logging.setMDC`|If you want to set MDC entries within the log entry, set this value to `true`. Your logging system must be configured to support MDC in order to format this data.|false|
|`druid.request.logging.setContextMDC`|Set to "true" to add the Druid query `context` to the MDC entries. Only applies when `setMDC` is `true`.|false|

For native query, the following MDC fields are populated with `setMDC`:
For a native query, the following MDC fields are populated when `setMDC` is `true`:

|MDC field|Description|
|---------|-----------|
@@ -310,31 +311,36 @@ For native query, the following MDC fields are populated with `setMDC`:
|`resultOrdering`|The ordering of results|
|`descending`|If the query is a descending query|

#### Filtered Request Logging
Filtered Request Logger filters requests based on a configurable query/time threshold (for native query) and sqlQuery/time threshold (for SQL query).
For native query, only request logs where query/time is above the threshold are emitted. For SQL query, only request logs where sqlQuery/time is above the threshold are emitted.
#### Filtered request logging

The `filtered` request logger filters requests based on the query type or how long a query takes to complete.
For native queries, the logger only logs requests when the `query/time` metric exceeds the threshold provided in `queryTimeThresholdMs`.
For SQL queries, it only logs requests when the `sqlQuery/time` metric exceeds threshold provided in `sqlQueryTimeThresholdMs`.
See [Metrics](../operations/metrics.md) for more details on query metrics.

Requests that meet the threshold are logged using the request logger type set in `druid.request.logging.delegate.type`.

|Property|Description|Default|
|--------|-----------|-------|
|`druid.request.logging.queryTimeThresholdMs`|Threshold value for query/time in milliseconds.|0, i.e., no filtering|
|`druid.request.logging.sqlQueryTimeThresholdMs`|Threshold value for sqlQuery/time in milliseconds.|0, i.e., no filtering|
|`druid.request.logging.queryTimeThresholdMs`|Threshold value for the `query/time` metric in milliseconds.|0, i.e., no filtering|
|`druid.request.logging.sqlQueryTimeThresholdMs`|Threshold value for the `sqlQuery/time` metric in milliseconds.|0, i.e., no filtering|
|`druid.request.logging.mutedQueryTypes` | Query requests of these types are not logged. Query types are defined as string objects corresponding to the "queryType" value for the specified query in the Druid's [native JSON query API](http://druid.apache.org/docs/latest/querying/querying). Misspelled query types will be ignored. Example to ignore scan and timeBoundary queries: ["scan", "timeBoundary"]| []|
|`druid.request.logging.delegate.type`|Type of delegate request logger to log requests.|none|

#### Composite Request Logging
Composite Request Logger emits request logs to multiple request loggers.
#### Composing request logging
The `composing` request logger emits request logs to multiple request loggers.

|Property|Description|Default|
|--------|-----------|-------|
|`druid.request.logging.loggerProviders`|List of request loggers for emitting request logs.|none|

#### Switching Request Logging
Switching Request Logger routes native query's request logs to one request logger and SQL query's request logs to another request logger.
#### Switching request logging
The `switching` request logger routes native query request logs to one request logger and SQL query request logs to another request logger.

|Property|Description|Default|
|--------|-----------|-------|
|`druid.request.logging.nativeQueryLogger`|request logger for emitting native query's request logs.|none|
|`druid.request.logging.sqlQueryLogger`|request logger for emitting SQL query's request logs.|none|
|`druid.request.logging.nativeQueryLogger`|Request logger for emitting native query request logs.|none|
|`druid.request.logging.sqlQueryLogger`|Request logger for emitting SQL query request logs.|none|

### Audit Logging

@@ -355,7 +361,7 @@ You can configure Druid processes to emit [metrics](../operations/metrics.md) re
|--------|-----------|-------|
|`druid.monitoring.emissionPeriod`| Frequency that Druid emits metrics.|`PT1M`|
|[`druid.monitoring.monitors`](#metrics-monitors)|Sets list of Druid monitors used by a process.|none (no monitors)|
|[`druid.emitter`](#metrics-emitters)|Setting this value initializes one of the emitter modules.|`noop`|
|[`druid.emitter`](#metrics-emitters)|Setting this value initializes one of the emitter modules.|`noop` (metric emission disabled by default)|

#### Metrics monitors

@@ -380,20 +386,22 @@ Metric monitoring is an essential part of Druid operations. The following monit

For example, you might configure monitors on all processes for system and JVM information within `common.runtime.properties` as follows:

`druid.monitoring.monitors=["org.apache.druid.java.util.metrics.SysMonitor","org.apache.druid.java.util.metrics.JvmMonitor"]`
```
druid.monitoring.monitors=["org.apache.druid.java.util.metrics.SysMonitor","org.apache.druid.java.util.metrics.JvmMonitor"]
```

You can override cluster-wide configuration by amending the `runtime.properties` of individual processes.

#### Metrics emitters

There are several emitters available:

- `noop` (default)
- log4j ([`logging`](#logging-emitter-module))
- POSTs of JSON events ([`http`](#http-emitter-module))
- [`parametrized`](#parametrized-http-emitter-module)
- [`composing`](#composing-emitter-module) to initialize multiple emitter modules
- [`graphite`](#graphite-emitter)
- `noop` (default) disables metric emission.
- [`logging`](#logging-emitter-module) emits logs using Log4j2.
- [`http`](#http-emitter-module) sends `POST` requests of JSON events.
- [`parametrized`](#parametrized-http-emitter-module) operates like the `http` emitter but fine-tunes the recipient URL based on the event feed.
- [`composing`](#composing-emitter-module) initializes multiple emitter modules.
- [`graphite`](#graphite-emitter) emits metrics to a [Graphite](https://graphiteapp.org/) Carbon service.

##### Logging Emitter Module

@@ -436,11 +444,14 @@ The following properties allow the HTTP Emitter to use its own truststore config

##### Parametrized HTTP Emitter Module

`druid.emitter.parametrized.httpEmitting.*` configs correspond to the configs of HTTP Emitter Modules, see above.
Except `recipientBaseUrl`. E.g., `druid.emitter.parametrized.httpEmitting.flushMillis`,
`druid.emitter.parametrized.httpEmitting.flushCount`, `druid.emitter.parametrized.httpEmitting.ssl.trustStorePath`, etc.
The parametrized emitter takes the same configs as the [`http` emitter](#http-emitter-module) using the prefix `druid.emitter.parametrized.httpEmitting.`.
For example:
* `druid.emitter.parametrized.httpEmitting.flushMillis`
* `druid.emitter.parametrized.httpEmitting.flushCount`
* `druid.emitter.parametrized.httpEmitting.ssl.trustStorePath`

The additional configs are:
Do not specify `recipientBaseUrl` with the parametrized emitter.
Instead use `recipientBaseUrlPattern` described in the table below.

|Property|Description|Default|
|--------|-----------|-------|
@@ -454,7 +465,7 @@ The additional configs are:

##### Graphite Emitter

To use graphite as emitter set `druid.emitter=graphite`. For configuration details please follow this [link](../development/extensions-contrib/graphite.md).
To use graphite as emitter set `druid.emitter=graphite`. For configuration details, see [Graphite emitter](../development/extensions-contrib/graphite.md) for the Graphite emitter Druid extension.


### Metadata storage

0 comments on commit 9ed7aa3

Please sign in to comment.