mirror of https://github.com/hashicorp/boundary
Sink documentation (#1449)
Jim
5 years ago
committed by
GitHub
parent
534efef039
commit
b3d8b50307
@ -0,0 +1,97 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Filtering - Events
|
||||
description: |-
|
||||
How to filter events emitted by Boundary.
|
||||
---
|
||||
|
||||
This page describes how to filter events written to Boundary event sinks.
|
||||
|
||||
~> This feature was introduced in Boundary 0.5.0.
|
||||
|
||||
# Event Filtering
|
||||
|
||||
Starting in Boundary 0.5.0, a variety of event types (error, observation,
|
||||
system, etc) are emitted from Boundary. Boundary events can be emitted in
|
||||
several formats including [cloudevents](https://github.com/cloudevents/spec) and
|
||||
[hclog](https://github.com/hashicorp/go-hclog), and can be encoded as text and
|
||||
json.
|
||||
|
||||
Boundary allows you to configure any number of
|
||||
[sinks](/docs/configuration/events/overview), where these events will be
|
||||
written. When configuring an event sink, you can specify [common sink
|
||||
parameters](/docs/configuration/events/common) which include both
|
||||
`allow_filters` and `deny_filters` which use the standard [filter
|
||||
syntax](/docs/concepts/filtering) used
|
||||
elsewhere in Boundary.
|
||||
|
||||
Example events encoded as cloudevents-text. The first event is a system event
|
||||
and the second event is an observation event.
|
||||
```json
|
||||
{
|
||||
"id": "DU7u227Jhc",
|
||||
"source": "https://hashicorp.com/boundary/dev-controller/boundary-dev",
|
||||
"specversion": "1.0",
|
||||
"type": "system",
|
||||
"data": {
|
||||
"version": "v0.1",
|
||||
"op": "worker.(Worker).createClientConn",
|
||||
"data": {
|
||||
"address": "127.0.0.1:9201",
|
||||
"msg": "connected to controller"
|
||||
}
|
||||
},
|
||||
"datacontentype": "text/plain",
|
||||
"time": "2021-08-05T18:00:05.303435-04:00"
|
||||
}
|
||||
{
|
||||
"id": "s5ESg6CckX",
|
||||
"source": "https://hashicorp.com/boundary/dev-controller/boundary-dev",
|
||||
"specversion": "1.0",
|
||||
"type": "observation",
|
||||
"data": {
|
||||
"latency-ms": 202.995176,
|
||||
"request_info": {
|
||||
"id": "gtraceid_WiLnGzc2UHmNAYlcQ0sK",
|
||||
"method": "POST",
|
||||
"path": "/v1/auth-methods/ampw_1234567890:authenticate"
|
||||
},
|
||||
"start": "2021-08-05T18:00:34.032333-04:00",
|
||||
"status": 200,
|
||||
"stop": "2021-08-05T18:00:34.235335-04:00",
|
||||
"version": "v0.1"
|
||||
},
|
||||
"datacontentype": "text/plain",
|
||||
"time": "2021-08-05T18:00:34.235357-04:00"
|
||||
}
|
||||
```
|
||||
|
||||
If I wanted to filter an event sink which was configured for every event type to
|
||||
only include the above events, I might use the following sink configuration:
|
||||
```
|
||||
sink "stderr" = {
|
||||
name = "all-events"
|
||||
description = "All events sent to stderr"
|
||||
event_types = ["*"]
|
||||
format = "cloudevents-text"
|
||||
allow_filters = [
|
||||
'"/Data/request_info/Path" contains ":authenticate"'
|
||||
'"/Data/Op" contains ".createClientConn"'
|
||||
]
|
||||
# note: deny_filters are also supported.
|
||||
}
|
||||
```
|
||||
|
||||
When running `boundary dev` the example allow filter can be given via:
|
||||
```bash
|
||||
boundary dev \
|
||||
-event-allow-filter '"/Data/request_info/Path" contains ":authenticate"' \
|
||||
-event-allow-filter '"/Data/Op" contains ".createClientConn"'
|
||||
```
|
||||
~> Double quotes are part of the filter syntax; when using the CLI, it is likely
|
||||
easier to surround the filter with single quotes than to deal with escaping
|
||||
double quotes.
|
||||
|
||||
~> Both `-event-allow-filter` and `-event-deny-filter` command flags are
|
||||
supported for the `boundary dev` command.
|
||||
|
||||
@ -0,0 +1,36 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Controller/Worker - Events - Common Sink Parameters
|
||||
description: |-
|
||||
The common sink parameters for all sink types.
|
||||
---
|
||||
|
||||
# Common Sink Parameters
|
||||
|
||||
These parameters are shared across all sink types:
|
||||
|
||||
- `name` - Specify a name for the sink.
|
||||
|
||||
- `description` - Specify a description for the sink.
|
||||
|
||||
- `event_types` - Specifies a list of event types that will be sent to the sink.
|
||||
Can be `*`, `error`, `system`, `observation` or `audit`.
|
||||
|
||||
Note: `audit` events are a WIP and will only be emitted if they are both enabled and the env var `BOUNDARY_DEVELOPER_ENABLE_EVENTS` equals true. We anticipate many changes for audit events before they are generally available including what data is included and different options for redacting/encrypting that data.
|
||||
|
||||
- `event_source_url` - Specifies an optional event source URL for the sink. If
|
||||
not specified a default source will be composed of the
|
||||
https://hashicorp.com/boundary.io/ServerName/Path/FileName.
|
||||
|
||||
- `allow_filters` - Specifies a set predicates for including an event in the
|
||||
sink. If any filter matches, the event will be included. For more information,
|
||||
on using filters see: [event filtering](/docs/concepts/filtering/events)
|
||||
|
||||
- `deny-filters` - Specifies a set predicates for excluding an event in the
|
||||
sink. If any filter matches, the event will be excluded. For more information
|
||||
on using filters see: [event filtering](/docs/concepts/filtering/events)
|
||||
|
||||
- `format` - Specifies the format for the sink. Can be `cloudevents-json`,
|
||||
`cloudevents-text`, `hclog-json`, or `hclog-text`.
|
||||
|
||||
- `type` - Specifies the type of sink. Can be `stderr` or `file`.
|
||||
@ -0,0 +1,47 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Controller/Worker - Events - File Sink - Configuration
|
||||
description: |-
|
||||
The file sink configures Boundary to send events to a file.
|
||||
---
|
||||
|
||||
# `file` Sink
|
||||
|
||||
The file sink configures Boundary to send events to a file.
|
||||
|
||||
```hcl
|
||||
sink = {
|
||||
name = "obs-sink"
|
||||
description = "Observations sent to a file"
|
||||
event_types = ["observation"]
|
||||
format = "cloudevents-json"
|
||||
file {
|
||||
file_name = "file-name"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `sink` stanza may be specified more than once to make Boundary send events
|
||||
to multiple sinks; however, each file sink must have a unique `path` +
|
||||
`file_name`.
|
||||
|
||||
|
||||
## common parameters
|
||||
|
||||
These parameters are shared across all sink types: [common sink parameters](/docs/configuration/events/common)
|
||||
|
||||
## `file` parameters
|
||||
|
||||
These parameters are only valid for a `file` sink.
|
||||
|
||||
- `path` - Specifies the file path for the sink.
|
||||
|
||||
- `file_name` - Specifies the file name for the sink.
|
||||
|
||||
- `rotate_bytes` - Specifies the number of bytes that should trigger rotation of
|
||||
a file sink.
|
||||
|
||||
- `rotate_duration` - Specifies how often a file sink should be rotated.
|
||||
|
||||
- `rotate_max_files` - Specifies how many historical rotated files should be kept
|
||||
for a file sink.
|
||||
@ -0,0 +1,60 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Controller/Worker - Events
|
||||
description: |-
|
||||
The events stanza configures events-specific parameters.
|
||||
---
|
||||
|
||||
# `events` Stanza
|
||||
|
||||
The `events` stanza configures Boundary events-specific parameters.
|
||||
|
||||
Example:
|
||||
|
||||
```hcl
|
||||
events {
|
||||
observations_enabled = true
|
||||
sysevents_enabled = true
|
||||
sink "stderr" = {
|
||||
name = "all-events"
|
||||
description = "All events sent to stderr"
|
||||
event_types = ["*"]
|
||||
format = "hclog-text"
|
||||
}
|
||||
sink = {
|
||||
name = "obs-sink"
|
||||
description = "Observations sent to a file"
|
||||
event_types = ["observation"]
|
||||
format = "cloudevents-json"
|
||||
file {
|
||||
file_name = "file-name"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `audit_enabled` - Specifies if audit events should be emitted.
|
||||
Note: audit events are a WIP and will only be emitted if they are both enabled and the env var `BOUNDARY_DEVELOPER_ENABLE_EVENTS` equals true. We anticipate many changes for audit events before they are generally available including what data is included and different options for redacting/encrypting that data.
|
||||
|
||||
- `observation_enabled` - Specifies if observation events should be emitted.
|
||||
|
||||
- `sysevents_enabled` - Specifies if system events should be emitted.
|
||||
|
||||
- `sink` - Specifies the configuration of an event sink. Currently, two types of
|
||||
sink are supported: [file](/docs/configuration/events/file) and [stderr](/docs/configuration/events/stderr). If no sinks are configured then all
|
||||
events will be sent to a default [stderr](/docs/configuration/events/stderr) sink. Events may be sent to multiple
|
||||
sinks.
|
||||
|
||||
## Default Events Stanza
|
||||
If no event stanza is specified then the following default is used:
|
||||
```hcl
|
||||
events {
|
||||
audit_enabled = false
|
||||
observations_enabled = true
|
||||
sysevents_enabled = true
|
||||
sink "stderr" = {
|
||||
name = "default"
|
||||
event_types = ["*"]
|
||||
format = "cloudevents-json"
|
||||
}
|
||||
```
|
||||
@ -0,0 +1,28 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Controller - Events - stderr Sink - Configuration
|
||||
description: |-
|
||||
The stderr sink configures Boundary to send events to a stderr.
|
||||
---
|
||||
|
||||
# `stderr` Sink
|
||||
|
||||
The stderr sink configures Boundary to send events to a stderr.
|
||||
|
||||
```hcl
|
||||
|
||||
sink "stderr" = {
|
||||
name = "all-events"
|
||||
description = "All events sent to stderr"
|
||||
event_types = ["*"]
|
||||
format = "hclog-text"
|
||||
}
|
||||
```
|
||||
|
||||
## common parameters
|
||||
|
||||
These parameters are shared across all sink types: [common sink parameters](/docs/configuration/events/common)
|
||||
|
||||
## `stderr` parameters
|
||||
|
||||
There are parameters are only valid for a `stderr` sink.
|
||||
Loading…
Reference in new issue