From 08a12fba335a726ec66f27811560354f445ce6d4 Mon Sep 17 00:00:00 2001 From: cswatt Date: Mon, 25 Jan 2021 14:19:59 -0800 Subject: [PATCH] redoing branch (#9574) * redoing branch * fixing links --- content/en/dashboards/widgets/event_stream.md | 85 +++++++++++ content/en/events/_index.md | 142 +++++++++++++++++- content/en/monitors/monitor_types/event.md | 48 +++++- 3 files changed, 269 insertions(+), 6 deletions(-) diff --git a/content/en/dashboards/widgets/event_stream.md b/content/en/dashboards/widgets/event_stream.md index a248473096bd7..413663c5d08d9 100644 --- a/content/en/dashboards/widgets/event_stream.md +++ b/content/en/dashboards/widgets/event_stream.md @@ -13,6 +13,51 @@ further_reading: text: "Building Dashboard using JSON" --- +{{< site-region region="us" >}} + +The event stream is a widget version of the stream of events on the [Event Stream view][1]. + +Note: **this widget displays only the 100 most recent events**. + +{{< img src="dashboards/widgets/event_stream/event_stream.png" alt="event stream" >}} + +## Setup + +{{< img src="dashboards/widgets/event_stream/event_stream_setup.png" alt="event stream setup" style="width:80%;">}} + +### Configuration + +1. Enter a [search query][1] to filter the event stream. +2. On screenboards only, choose whether your widget has a custom timeframe or the screenboard's global timeframe. +3. Use the size parameter to choose to display either only the events title or the full event body. + +### Options + +#### Title + +Display a custom title for your widget by activating the `Show a Title` check box: + +{{< img src="dashboards/widgets/options/title.png" alt="Widget title" style="width:80%;">}} + +Optionally define its size and alignment. + +## API + +This widget can be used with the **Dashboards API**. Refer to the [Dashboards API][2] documentation for additional reference. + +The dedicated [widget JSON schema definition][3] for the event stream widget is: + +{{< dashboards-widgets-api >}} + +[1]: /events/ +[2]: /api/v1/dashboards/ +[3]: /dashboards/graphing_json/widget_json/ +[4]: /events/#event-explorer + +{{< /site-region >}} + +{{< site-region region="eu" >}} + The event stream is a widget version of the stream of events on the [Event Stream view][1]. Note: **this widget displays only the 100 most recent events**. @@ -47,6 +92,45 @@ The dedicated [widget JSON schema definition][3] for the event stream widget is: {{< dashboards-widgets-api >}} +[1]: /events/ +[2]: /api/v1/dashboards/ +[3]: /dashboards/graphing_json/widget_json/ +[4]: /events/#event-explorer +{{< /site-region >}} + +{{< site-region region="gov" >}} + +The event stream is a widget version of the stream of events on the [Event Explorer view][4]. + +## Setup + +### Configuration + +1. Enter a [search query][4] to filter the event stream. +2. On screenboards only, choose whether your widget has a custom timeframe or the screenboard's global timeframe. +3. Use the size parameter to choose to display either only the events title or the full event body. + +### Options + +#### Title + +Display a custom title for your widget by activating the `Show a Title` check box. + +Optionally define its size and alignment. + +## API + +This widget can be used with the **Dashboards API**. Refer to the [Dashboards API][2] documentation for additional reference. + +The dedicated [widget JSON schema definition][3] for the event stream widget is: + +{{< dashboards-widgets-api >}} + +[1]: /events/ +[2]: /api/v1/dashboards/ +[3]: /dashboards/graphing_json/widget_json/ +[4]: /events/#event-explorer +{{< /site-region >}} ## Further Reading {{< partial name="whats-next/whats-next.html" >}} @@ -54,3 +138,4 @@ The dedicated [widget JSON schema definition][3] for the event stream widget is: [1]: /events/ [2]: /api/v1/dashboards/ [3]: /dashboards/graphing_json/widget_json/ +[4]: /events/#event-explorer diff --git a/content/en/events/_index.md b/content/en/events/_index.md index 28b0c0c1ff0f2..ba62e3a285e85 100644 --- a/content/en/events/_index.md +++ b/content/en/events/_index.md @@ -16,10 +16,30 @@ further_reading: An event represents any record of activity noteworthy for engineers (devs, ops, and security). See the developer documentation to learn about [submitting events][1] to Datadog. +{{< site-region region="us" >}} ## Event stream The [event stream][2] is a display of the most recent events generated by your infrastructure and the associated monitors. +[2]: https://app.datadoghq.com/event/stream + +{{< /site-region >}} +{{< site-region region="eu" >}} +## Event stream + +The [event stream][3] is a display of the most recent events generated by your infrastructure and the associated monitors. + +[3]: https://app.datadoghq.eu/event/stream +{{< /site-region >}} +{{< site-region region="gov" >}} +## Event explorer + +The [event explorer][4] is a display of the most recent events generated by your infrastructure and the associated monitors. You can customize the columns displayed by using the **Options** button to the top right of the events. + + +[4]: https://gov.datadoghq.com/event/stream +{{< /site-region >}} + ### Search #### Full text @@ -30,6 +50,17 @@ Full text search works on all keywords provided in the search query after applyi Target specific event properties using these prefixes: + +{{< site-region region="us" >}} +| Filter | Description | +|---------------------------------|--------------------------------------------------------------------------------| +| `sources:github,chef` | Show events from GitHub OR Chef. | +| `tags:env-prod,db` | Show events tagged with #env-prod OR #db. | +| `hosts:i-0ade23e6,db.myapp.com` | Show events from i-0ade23e6 OR db.myapp.com. | +| `status:error` | Show events with an error status (supports: `error`, `warning`, `success`). | +| `priority:low` | Show only low-priority events (supports `low` or `normal`, defaults to `all`). | +{{< /site-region >}} +{{< site-region region="eu" >}} | Filter | Description | |---------------------------------|--------------------------------------------------------------------------------| | `sources:github,chef` | Show events from GitHub OR Chef. | @@ -37,9 +68,85 @@ Target specific event properties using these prefixes: | `hosts:i-0ade23e6,db.myapp.com` | Show events from i-0ade23e6 OR db.myapp.com. | | `status:error` | Show events with an error status (supports: `error`, `warning`, `success`). | | `priority:low` | Show only low-priority events (supports `low` or `normal`, defaults to `all`). | +{{< /site-region >}} +{{< site-region region="gov" >}} +| Filter | Description | +|---------------------------------|--------------------------------------------------------------------------------| +| `source:github,chef` | Show events from GitHub OR Chef. | +| `host:i-0ade23e6,db.myapp.com` | Show events from i-0ade23e6 OR db.myapp.com. | +| `service:kafka` | Show events from the `kafka` service. | +| `status:error` | Show events with an error status (supports: `error`, `warning`, `success`). | +| `role:` | | +| `availability-zone:us-east-1a` | Show events in the `us-east-1a` AWS availability zone (AZ). | +| `container_id:foo` | Show events from the container with the ID `foo`. | +| `@evt.name:foo` | Show the event named `foo`. | + +{{< /site-region >}} **Note**: Filters perform an exact match search. Partial strings are not considered. +{{< site-region region="gov" >}} +#### Context + +Build up a context to explore your events in your Event Explorer page first by selecting the proper time range, and then by using the search bar to filter your events and analytics. + +#### Facets and measures + +After being collected, your events attributes can be indexed as facets or measures. On the left side, you can use facets and measures to filter your results. You can create new facets or measures from existing event tags or attributes. + +A **facet** displays all the distinct members of an attribute or a tag and provides some basic analytics, such as the number of events represented. Facets allow you to pivot or filter your datasets based on a given attribute. To filter, select the values that you want to see. to start using an attribute as a facet, click on it. Use the option to **Create facet**.The value of this attribute is stored for all new events. + +A **measure** is an attribute with a numerical value contained in your event. To start using an attribute as a measure, click on a numerical attribute. Use the option to **Create measure**. The value of this attribute is stored for all new events. + +#### Saved views + +Use saved views to automatically configure your event explorer with a preselected set of facets, measures, searches, time ranges, and visualizations. Check the dedicated [saved views documentation][5] to learn more. + + +[5]: logs/explorer/saved_views/ +{{< /site-region >}} + +{{< site-region region="us" >}} +#### Advanced + +For a more advanced search, use the Datadog event query language, for example: + +| Filter | Description | +|---------------------------------------------------|---------------------------------------------------------------------------| +| `tags:env-prod OR db` | Show events tagged with #env-prod OR #db. | +| `tags:security-group:sg-123 AND role:common-node` | Show events tagged with `#security-group:sg-123` AND `#role:common-node`. | +| `cloud_provider:* NOT "azure"` | Show all cloud providers except the ones tagged with "azure". | + +Use tag search to find all events with the same key tag, for example: + +| Filter | Description | +|----------------------|--------------------------------------------------------------------------------------| +| `tags::` | Shows events with the `:` tag. | +| `:*` | Shows all events with the `` attached. | +| ``:`` | Shows all events with `:` tag where the `` matches the ``. | +| `tags:` | This is not a valid search. | +| `:` | This is not a valid search. | + +To combine multiple terms into a complex query, use the following Boolean operators: + +| Operator | Description | Example | +|----------|-----------------------------------------------------------------------------------------------------------------------|-------------------------------------------| +| `AND` | **Intersection**: both terms are in the selected events (for tags, if nothing is added, `AND` is the default). | `redis_* AND down` | +| `OR` | **Union**: either term is contained in the selected events. Use a comma (`,`) for tags. | `sources:nagios,chef directory OR Mixlib` | +| `NOT` | **Exclusion**: the following term is NOT in the event. This operator works for strings only—use `-` in front of tags. | `-tags:: NOT ""` | + +**Note**: Some of the advanced query language features like Boolean logic work only in the event stream page, and are not available in graph tiles or dashboard widgets. + +Combine prefixes to construct more complex searches. For example, to find all open `chef` or `nagios` errors that mention `cassandra`, use: + +```text +sources:nagios,chef status:error cassandra +``` + +**Note**: Do not use spaces after the colon or commas in these lists. Anything not attached to a prefix goes to full text search. +{{< /site-region >}} + +{{< site-region region="eu" >}} #### Advanced For a more advanced search, use the Datadog event query language, for example: @@ -77,12 +184,39 @@ sources:nagios,chef status:error cassandra ``` **Note**: Do not use spaces after the colon or commas in these lists. Anything not attached to a prefix goes to full text search. +{{< /site-region >}} + +{{< site-region region="gov" >}} +#### Advanced + +For a more advanced search, use the Datadog log query language. See the [Log Search Syntax][6] documentation for more details. +To combine multiple terms into a complex query, use the following Boolean operators: + +| Operator | Description | Example | +|----------|-----------------------------------------------------------------------------------------------------------------------|-------------------------------------------| +| `AND` | **Intersection**: both terms are in the selected events (for tags, if nothing is added, `AND` is the default). | `redis_* AND down` | +| `OR` | **Union**: either term is contained in the selected events. Use a comma (`,`) for tags. | `sources:nagios,chef directory OR Mixlib` | +| `NOT` | **Exclusion**: the following term is NOT in the event. This operator works for strings only—use `-` in front of tags. | `-tags:: NOT ""` | + +[6]: logs/search_syntax/ + +{{< /site-region >}} + +{{< site-region region="us" >}} +### Aggregation + +By default, related events are aggregated when displayed in the events stream. To show unaggregated events, un-check the **Aggregate related events** box at the top right of your event stream: + +{{< img src="events/event_stream_aggregated.png" alt="Aggregated event stream" style="width:50%;" >}} +{{< /site-region >}} +{{< site-region region="eu" >}} ### Aggregation By default, related events are aggregated when displayed in the events stream. To show unaggregated events, un-check the **Aggregate related events** box at the top right of your event stream: {{< img src="events/event_stream_aggregated.png" alt="Aggregated event stream" style="width:50%;" >}} +{{< /site-region >}} ### Notifications @@ -95,7 +229,7 @@ Datadog supports `@notifications` in the event stream, for example: | `@john` | Notifies the user named `john`. | | `@test@example.com` | Sends an email to `test@example.com`. | | `@slack--` | Posts the event or graph to the specified Slack channel. | -| `@webhook` | Alerts or triggers the webhook. See the [blog post on webhooks][3]. | +| `@webhook` | Alerts or triggers the webhook. See the [blog post on webhooks][7]. | | `@pagerduty` | Sends an alert to Pagerduty. You can also use `@pagerduty-acknowledge` and `@pagerduty-resolve`. | ## Further Reading @@ -104,4 +238,8 @@ Datadog supports `@notifications` in the event stream, for example: [1]: /developers/events/ [2]: https://app.datadoghq.com/event/stream -[3]: https://www.datadoghq.com/blog/send-alerts-sms-customizable-webhooks-twilio +[3]: https://app.datadoghq.eu/event/stream +[4]: https://gov.datadoghq.com/event/stream +[5]: logs/explorer/saved_views/ +[6]: logs/search_syntax/ +[7]: https://www.datadoghq.com/blog/send-alerts-sms-customizable-webhooks-twilio diff --git a/content/en/monitors/monitor_types/event.md b/content/en/monitors/monitor_types/event.md index aa02e190ce833..1725659cba27e 100644 --- a/content/en/monitors/monitor_types/event.md +++ b/content/en/monitors/monitor_types/event.md @@ -22,6 +22,7 @@ Event monitors allow you to alert on events matching a search query. To create a [event monitor][1] in Datadog, use the main navigation: *Monitors --> New Monitor --> Event*. +{{< site-region region="us" >}} ### Select events to count As you fill in the parameters below, the list of events above the search fields is filtered. @@ -37,6 +38,44 @@ Choose your alert grouping: * **Simple alert** aggregates all reporting sources. You receive one alert when the aggregated value meets the set conditions. * **Multi alert** applies the alert to each source according to your group parameters. You receive an alert for each group that meets the set conditions. +{{< /site-region >}} +{{< site-region region="eu" >}} + +### Select events to count + +As you fill in the parameters below, the list of events above the search fields is filtered. + +* Match events containing `` +* with status `error`, `warning`, `info`, or `success` +* and priority `all`, `normal`, or `low` +* from `` +* over `` +* exclude `` + +Choose your alert grouping: + +* **Simple alert** aggregates all reporting sources. You receive one alert when the aggregated value meets the set conditions. +* **Multi alert** applies the alert to each source according to your group parameters. You receive an alert for each group that meets the set conditions. +{{< /site-region >}} +{{< site-region region="gov" >}} + +### Define the search query + +As you define the search query, the top graph updates. + +1. Construct a search query using the same logic as a [log explorer search][2]. +2. Choose to monitor over an event count, facet, or measure: + * **Monitor over an event count**: Use the search bar (optional) and do **not** select a facet or measure. Datadog evaluates the number of events over a selected time frame, then compares it to the threshold conditions. + * **Monitor over a facet**: If a facet is selected, the monitor alerts over the unique value count of the facet. + * **Monitor over measure**: If a measure is selected, the monitor alerts over the numerical value of the event facet (similar to a metric monitor) and aggregation needs to be selected (`min`, `avg`, `sum`, `median`, `pc75`, `pc90`, `pc95`, `pc98`, `pc99`, or `max`). +3. Configure the alerting grouping strategy (optional): + * **Simple-Alert**: Simple alerts aggregate over all reporting sources. You receive one alert when the aggregated value meets the set conditions. This works best to monitor a metric from a single host or the sum of a metric across many hosts. This strategy may be selected to reduce notification noise. + * **Multi-Alert**: Multi alerts apply the alert to each source according to your group parameters, up to 100 matching groups. An alerting event is generated for each group that meets the set conditions. For example, you could group `system.disk.in_use` by `device` to receive a separate alert for each device that is running out of space. + +[2]: /logs/explorer + +{{< /site-region >}} + ### Set alert conditions @@ -44,11 +83,11 @@ Choose your alert grouping: * `` * during the last `5 minutes`, `15 minutes`, `1 hour`, etc. or `custom` to set a value between 5 minutes and 48 hours. -**Note**: Some providers introduce a significant delay between when an event is **posted**, and when the event is initiated. In this case, Datadog back-dates the event to the time of occurrence, which could place an incoming event outside the current monitor evaluation window. Widening your evaluation window can help account for the time difference. If you need help adjusting your monitor settings appropriately, reach out to [Datadog Support][2]. +**Note**: Some providers introduce a significant delay between when an event is **posted**, and when the event is initiated. In this case, Datadog back-dates the event to the time of occurrence, which could place an incoming event outside the current monitor evaluation window. Widening your evaluation window can help account for the time difference. If you need help adjusting your monitor settings appropriately, reach out to [Datadog Support][3]. ### Notifications -For detailed instructions on the **Say what's happening** and **Notify your team** sections, see the [Notifications][3] page. +For detailed instructions on the **Say what's happening** and **Notify your team** sections, see the [Notifications][4] page. #### Event template variables @@ -77,5 +116,6 @@ The template variable is `{{event.tags.env}}`. The result of using this template {{< partial name="whats-next/whats-next.html" >}} [1]: https://app.datadoghq.com/monitors#create/event -[2]: /help/ -[3]: /monitors/notifications/ +[2]: /logs/explorer +[3]: /help/ +[4]: /monitors/notifications/