diff --git a/website/content/docs/concepts/filtering/events.mdx b/website/content/docs/concepts/filtering/events.mdx index bf7833fe35..74f45b9827 100644 --- a/website/content/docs/concepts/filtering/events.mdx +++ b/website/content/docs/concepts/filtering/events.mdx @@ -65,7 +65,8 @@ and the second event is an observation event. To filter an event sink which was configured for every event type to only include the above events, use the following sink configuration: -``` + +```hcl sink "stderr" = { name = "all-events" description = "All events sent to stderr" diff --git a/website/content/docs/configuration/events/configure-events.mdx b/website/content/docs/configuration/events/configure-events.mdx new file mode 100644 index 0000000000..a65c45b14b --- /dev/null +++ b/website/content/docs/configuration/events/configure-events.mdx @@ -0,0 +1,70 @@ +--- +layout: docs +page_title: Configure events +description: >- + Configure log event sinks for controllers and workers to monitor Boundary resources and actions. +--- + +# Configure event logging + +The [`events`](/boundary/docs/configuration/events) stanza lets you log system information in a well-defined, structured format that gives you visibility into emitted events. + +You configure emitted events and sinks in the configuration file for any [controller](/boundary/docs/configuration/controller) or [worker](/boundary/docs/configuration/worker) server. +Complete the following steps to configure events: + +1. Open the configuration file for the controller or worker server that you want to emit events. +1. Edit the `events` stanza in the configuration file. +Set the following to `true` to emit that type of event, and then configure any sinks: + - `audit_enabled` - Specifies if Boundary emits audit events. + - `observations_enabled` - Specifies if Boundary emits observation events. + - `sysevents_enabled` - Specifies if Boundary should emit system events. + - `telemetry_enabled` - Specifies if Boundary should emit telemetry events. +To receive telemetry events, you must also set `observations_enabled` to `true`. +1. Save the file. + +The following example includes the contents of the `events` stanza in the `compose/controller.hcl` configuration file: + + + +```hcl +events { + audit_enabled = true + observations_enabled = true + sysevents_enabled = true + telemetry_enabled = true + + sink "stderr" { + name = "all-events" + description = "All events sent to stderr" + event_types = ["*"] + format = "cloudevents-json" + } + + sink { + name = "controller-audit-sink" + description = "Audit sent to a file" + event_types = ["audit"] + format = "cloudevents-json" + + file { + path = "/logs" + file_name = "controller.log" + } + + audit_config { + audit_filter_overrides { + secret = "encrypt" + sensitive = "hmac-sha256" + } + } + } +} +``` + + + +## More information + +Refer to the `events` stanza [Overview](/boundary/docs/configuration/events) for more information about monitoring events for a controller or worker. + +Refer to [Telemetry data](/boundary/docs/configuration/events/telemetry-data) for a list of the events and data you can track by enabling telemetry events. \ No newline at end of file diff --git a/website/content/docs/configuration/events/index.mdx b/website/content/docs/configuration/events/index.mdx index 613e28baba..4bf19d8896 100644 --- a/website/content/docs/configuration/events/index.mdx +++ b/website/content/docs/configuration/events/index.mdx @@ -1,14 +1,33 @@ --- layout: docs page_title: Controller/worker - events -description: |- - The events stanza configures events-specific parameters. +description: >- + Learn about using the events stanza to configure events-specific parameters. --- # `events` stanza +You can log system information in a well-defined, structured format that give you visibility into emitted events. +You configure emitted events and sinks in the configuration file for any [controller](/boundary/docs/configuration/controller) or [worker](/boundary/docs/configuration/worker) server. The `events` stanza configures Boundary events-specific parameters. +You can specify what types of events Boundary should emit: + +- `audit_enabled` - Specifies if Boundary emits audit events. +- `observations_enabled` - Specifies if Boundary emits observation events. +- `sysevents_enabled` - Specifies if Boundary should emit system events. +- `telemetry_enabled` - Specifies if Boundary should emit telemetry events. +To receive telemetry events, you must also set `observations_enabled` to `true`. + +Event sinks provide a location for Boundary to write events to. +You can configure sinks to allow or deny specific event types using filter syntax: + +- `sink` - Specifies the configuration of an event sink. +Currently, two types of sinks are supported: [file](/boundary/docs/configuration/events/file) and [stderr](/boundary/docs/configuration/events/stderr). + +You can repeat the `sink` stanza more than once to send events to multiple sinks, but each file sink must have a unique path and file name. +If no sinks are configured, then all events will be sent to a default [stderr](/boundary/docs/configuration/events/stderr) sink. + Example: ```hcl @@ -35,20 +54,6 @@ events { } ``` -- `audit_enabled` - Specifies if audit events should be emitted. - -- `observations_enabled` - Specifies if observation events should be emitted. - -- `sysevents_enabled` - Specifies if system events should be emitted. - -- `telemetry_enabled` - Specifies if telemetry events should be emitted. -To receive telemetry events, you must also set `observations_enabled` to `true`. - -- `sink` - Specifies the configuration of an event sink. Currently, two types of - sink are supported: [file](/boundary/docs/configuration/events/file) and [stderr](/boundary/docs/configuration/events/stderr). If no sinks are configured then all - events will be sent to a default [stderr](/boundary/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: @@ -66,3 +71,13 @@ events { } } ``` + +## Next steps + +Refer to [Configure event logging](/boundary/docs/configuration/events/configure-events) to configure a controller or worker server to emit events. + +Refer to [Telemetry data](/boundary/docs/configuration/events/telemetry-data) for a list of the events and data you can track by enabling telemetry events. + +## Tutorial + +Refer to the [Event filtering and sink configuration](/boundary/tutorials/self-managed-deployment/event-logging) tutorial to learn how to define an event sink and configure logging. \ No newline at end of file diff --git a/website/content/docs/configuration/events/telemetry-data.mdx b/website/content/docs/configuration/events/telemetry-data.mdx new file mode 100644 index 0000000000..60cb9c953b --- /dev/null +++ b/website/content/docs/configuration/events/telemetry-data.mdx @@ -0,0 +1,586 @@ +--- +layout: docs +page_title: Telemetry data +description: >- + Learn what data Boundary captures when telemetry is enabled and how you can view it. +--- + +# Telemetry data + +If you have telemetry enabled in Boundary, you can view information about the following resources. + +## Auth methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventsTelemetry fields
Auth methods (Create)Auth method ID
Auth method type
Auth method URI
Link (Includes location: org ID, project ID, and internal ID)
Scope ID
Scope type
Timestamp
Auth methods (Delete)Auth method ID
Link (Includes location: org ID, project ID, and internal ID)
Timestamp
Auth methods user authenticateAccount ID
Auth method ID
Link (Includes location: org ID, project ID, and internal ID)
Scope ID
Scope type
Timestamp
User ID
+ +## Connections + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventsTelemetry fields
Connections authorizedConnection ID
Connections left
Connection limit
Connection status
Connection type
Link (Includes location: org ID, project ID, and internal ID)
Session ID
Timestamp
Worker ID
Connections closedConnection ID
Link (Includes location: org ID, project ID, and internal ID)
Timestamp
Connections connectedConnection ID
Connection status
Connection type
Link (Includes location: org ID, project ID, and internal ID)
Timestamp
+ +## Groups + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventsTelemetry fields
Group add memberHCP Boundary user ID
Link (Includes location: org ID, project ID, and internal ID)
Parent scope ID
Scope ID
Timestamp
Group remove memberHCP Boundary user ID
Link (Includes location: org ID, project ID, and internal ID)
Parent scope ID
Scope ID
Timestamp
Group set memberHCP Boundary user ID
Link (Includes location: org ID, project ID, and internal ID)
Parent scope ID
Scope ID
Timestamp
Groups (Create/delete)HCP Boundary user ID
Link (Includes location: org ID, project ID, and internal ID)
Parent scope ID
Scope ID
Timestamp
+ +## HCP Boundary + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventsTelemetry fields
HCP Boundary clusters createdBoundary version
Internal ID
Link (Includes location: org ID, project ID, and internal ID)
Organization ID
Principal ID
Principal type
Project ID
Provider
Region
Source channel
+ +## Host catalogs + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventsTelemetry fields
Host catalogs createdHost catalog ID
Host catalog type
Link (Includes location: org ID, project ID, and internal ID)
Parent scope ID
Plugin ID
Scope ID
Timestamp
Host catalogs deletedHost catalog ID
Link (Includes location: org ID, project ID, and internal ID)
Timestamp
+ +## Hosts + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventsTelemetry fields
Hosts createdHost catalog ID
Host ID
Host type
Link (Includes location: org ID, project ID, and internal ID)
Parent scope ID
Plugin ID
Scope ID
Timestamp
Hosts deletedHost catalog ID
Host ID
Link (Includes location: org ID, project ID, and internal ID)
Timestamp
+ +## Roles + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventsTelemetry fields
Roles addedHCP Boundary user ID
Link (Includes location: org ID, project ID, and internal ID)
Parent scope ID
Scope ID
Timestamp
Roles deletedLink (Includes location: org ID, project ID, and internal ID)
Role ID
Timestamp
+ +## Scopes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventsTelemetry fields
Org scopes (Create/delete)Organization ID
Parent scope ID
Timestamp
Project scopes (Create/delete)Link (Includes location: org ID, project ID, and internal ID)
Organization ID
Parent scope ID
Timestamp
+ +## Sessions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventsTelemetry fields
Sessions cancelledLink (Includes location: org ID, project ID, and internal ID)
Session ID
Session status
Timestamp
Session lookupConnections left
Connection limit
HCP Boundary user ID
Host ID
Host set ID
Link (Includes location: org ID, project ID, and internal ID)
Session ID
Session status
Timestamp
Worker ID
Target session authorizedHCP Boundary user ID
Host ID
Host set ID
Link (Includes location: org ID, project ID, and internal ID)
Parent scope ID
Scope ID
Session ID
Session type
Target ID
Timestamp
+ +## Targets + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventsTelemetry fields
Targets (Create)Link (Includes location: org ID, project ID, and internal ID)
Target ID
Timestamp
Targets (Delete)Link (Includes location: org ID, project ID, and internal ID)
Target ID
Timestamp
+ +## Users + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventsTelemetry fields
Users (Create/delete)HCP Boundary user ID
Link (Includes location: org ID, project ID, and internal ID)
Parent scope ID
Scope ID
Timestamp
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 239ee4e23c..735aae9b3f 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -573,6 +573,10 @@ "title": "Overview", "path": "configuration/events" }, + { + "title": "Configure event logging", + "path": "configuration/events/configure-events" + }, { "title": "Common sink parameters", "path": "configuration/events/common" @@ -584,6 +588,10 @@ { "title": "Stderr sink", "path": "configuration/events/stderr" + }, + { + "title": "Telemetry data", + "path": "configuration/events/telemetry-data" } ] },