Permalink
Browse files

WIP

  • Loading branch information...
thomashumio committed Jun 18, 2018
1 parent 500e7e7 commit c2e8ebb29248fb9a63f13280f74f715b3f188700
Showing with 683 additions and 663 deletions.
  1. +1 −1 README.md
  2. +1 −1 content/_index.md
  3. +87 −44 content/alerts/_index.md
  4. 0 content/alerts/{notifiers → }/email.md
  5. +0 −29 content/alerts/notifiers/_index.md
  6. 0 content/alerts/{notifiers → }/opsgenie.md
  7. 0 content/alerts/{notifiers → }/pagerduty.md
  8. 0 content/alerts/{notifiers → }/slack.md
  9. 0 content/alerts/{notifiers → }/victorops.md
  10. 0 content/alerts/{notifiers → }/webhook.md
  11. +1 −1 content/api/cluster-management-api.md
  12. +1 −1 content/api/ingest-api.md
  13. +1 −1 content/api/parser-api.md
  14. 0 content/{getting-started → appendix}/convincing-your-boss.md
  15. +1 −1 content/appendix/faq.md
  16. +0 −171 content/appendix/glossary.md
  17. +5 −4 content/{installation → appendix}/instance_sizing.md
  18. 0 content/{getting-started → appendix}/intro_to_log_management.md
  19. 0 content/{installation → configuration}/backup.md
  20. +0 −243 content/configuration/cluster_setup.md
  21. +3 −3 content/configuration/configuration_options.md
  22. 0 content/{installation/license_management.md → configuration/license-management.md}
  23. 0 content/{installation → configuration}/retention.md
  24. +4 −2 content/{installation → configuration}/upgrading.md
  25. +0 −14 content/getting-started/tutorial.md
  26. +1 −1 content/guides/bro.md
  27. +1 −1 content/guides/linux.md
  28. +2 −2 content/{getting-started → guides}/moving_from_elastic_stack.md
  29. +3 −80 content/installation/_index.md
  30. +24 −22 content/installation/{login.md → authentication.md}
  31. +3 −0 content/installation/aws.md
  32. +3 −0 content/installation/bare-metal.md
  33. +275 −0 content/installation/cluster_setup.md
  34. +80 −0 content/installation/docker.md
  35. +1 −1 content/parsers/_index.md
  36. +2 −2 content/parsers/parsing.md
  37. +5 −5 content/searching/_index.md
  38. +1 −1 content/sending-data/integrations/heroku.md
  39. +7 −5 content/{getting-started/hello-world.md → tutorial/_index.md}
  40. +1 −1 content/{getting-started → using-humio}/_index.md
  41. +19 −0 content/using-humio/data-sources.md
  42. +24 −0 content/using-humio/events.md
  43. +55 −0 content/using-humio/queries.md
  44. +1 −1 content/{getting-started → using-humio}/repositories.md
  45. +29 −0 content/using-humio/tags.md
  46. +2 −2 content/{getting-started/the_sandbox.md → using-humio/the-sandbox.md}
  47. +25 −0 content/using-humio/user-management.md
  48. +7 −7 content/{getting-started → using-humio}/views.md
  49. +0 −9 layouts/shortcodes/queryfunctions.html
  50. +7 −7 legacy/first-time-use.md
@@ -4,7 +4,7 @@
Official documentation for Humio

## Building docs
First, you need to make sure you have [Hugo installed](https://gohugo.io/getting-started/quick-start/#step-1-install-hugo) on your machine.
First, you need to make sure you have [Hugo installed](https://gohugo.io/using-humio/quick-start/#step-1-install-hugo) on your machine.
Then you can preview the docs by running
```
$ hugo server -D
@@ -41,4 +41,4 @@ and running it yourself, or creating a free account in [Humio Cloud](https://clo
</p>

Once you have access to running Humio instance, you can head over to
the [Hello World]({{< relref "hello-world.md" >}}) tutorial.
the [Hello World]({{< ref "tutorial/_index.md" >}}) tutorial.
@@ -1,33 +1,85 @@
---
title: "Alerts"
weight: 600
weight: 675
category_title: Overview
---
Humio has built-in support for alerting.
Every repository has it's own individual set of alerts.
The alert concept in Humio consists of two parts: *Notifiers* and *Alerts*.

Humio has the ability to reach out on various channels under some user configured circumstances.
Notifiers are the integration between Humio and _other_ systems. Currently e-mail
notifications and webhooks are supported along with a list of dedicated
integrations e.g. [Slack]({{< ref "slack.md" >}}).

## Concept
For instance, when an alert detects your accesslog has reached a set threshold
for Internal Server Errors, it will trigger a notifier that will send a message informing about the issue .

Every repository has it's own individual configuration. The Alert concept in Humio consists of two parts: *Notifiers* and *Alerts*.
## Alerts

Alerts are standard Live Queries that run continuously.
Alerts trigger whenever there is one or more rows in the search result.

Notifiers are the integration between Humio and _other_ systems. Currently e-mail and webhooks are supported along with a list of integrations.
**Example**
For instance an alarm can be configured to trigger whenever there's more than 5
status 500s in the accesslog.

Alerts are what triggers the notifiers. They are created using Humio's query language. For instance, when an alert detects your accesslog has reached a set threshold for Internal Server Errors, it will trigger a notifier that will send a message informing about the issue .
```humio
#type=accesslog statuscode=500
| count(as=internal_server_errors)
| internal_server_errors > 5
```

If there's less than 5 events in the time window the search will be an empty
result and nothing will happen.
On the other hand, if there's more than five events a non-empty result will be
returned and then alert will trigger the notifier.

## Types of alerts

Generally speaking, alerts can be divided into two groups:

* Single events, that can affect one or more users experience with the product.
Usually not something that should wake up engineers at night but could result
in an ticket on your issue tracker.
* Faulty state is when one or more components has reached a bad state and is
unable to function properly. This usually affects most users and is something
that should wake up engineers at night.

### Being Notified

When alerts trigger they are configured to send notifications using a notifier.

### Creating Alerts

The easiest way to create a new alert is by building up your query in the Search view.
Don't forget to set a Live time window for the search. And then hit the `Save As…` __→__ `Alert` option on the right.

Then give it a name, select a notifier and finally Notification Frequency.
The Notification Frequency is the minimum time before the same alert will be triggered again.

{{% notice tip %}}
For notifiers like E-mail and Slack you want a lower Notification Frequency (more time in-between) triggers since they don't do de-duplication.
{{% /notice%}}

<!--TODO: When Auto-cancel has been implemented, please reconsider guideline on Notification Frequency -->

## Notifiers

Our list of notifiers is ever growing and currently we do support the following services. We are constantly expanding what we support (If you don't see a service you need here, please contact [support@humio.com](mailto:support@humio.com?subject=Requesting alert notifier) and we will be happy to find a solution for you):
A notifier is a module that sends notifications when alerts trigger.


* [E-mail](/features/alerts/notifiers/email/)
* [Slack](/features/alerts/notifiers/slack/)
* [WebHook](/features/alerts/notifiers/webhook/)
* [OpsGenie](/features/alerts/notifiers/webhook/)
### Built-in Notifiers

Our list of notifiers is ever growing and currently we do support the following services.

* [Email]({{< ref "email.md" >}})
* [Slack]({{< ref "slack.md" >}})
* [Webhook]({{< ref "webhook.md" >}})
* [OpsGenie]({{< ref "opsgenie.md" >}})
<!--TODO: * PagerDuty-->
<!--TODO: * VictorOps-->


Creating a new Notifier is pretty simple. On the Alerts page there's a Notifiers pane on the left.
For a new repository this list will be empty.
Creating a new Notifier is pretty simple. On the Alerts Page there's a Notifiers menu item on the left.
To create a new one hit the "New Notifier" button on the top right.

First you'll need to select a type of notifier from the "Notifier Type" dropdown list
@@ -39,38 +91,29 @@ Make sure you give your notifiers a meaningful name, i.e. "OpsTeam",
"Backlog issues" etc. We will make sure that the type of the notifier is also displayed.
{{% /notice%}}

## Alerts
Alerts are pretty simple. First and foremost they are based on standard Humio
queries that a re running in a specified time window. An alert is connected to
a notifier, that will send a message when the alert fires.
Alerts trigger whenever there's one or more events in the search result.
For instance an Alarm can be configured to trigger whenever there's more than 5
status 500s in the accesslog.

```humio
#type=accesslog statuscode=500
| count(as=internal_server_errors)
| internal_server_errors > 5
```

If there's less than 5 events in the time window the search will be an empty
result and nothing will happen.
On the other hand, if there's more than five events a non-empty result will be
returned and then alert will trigger the notifier.
### Custom Notifiers

{{% notice note %}}
Generally speaking, alerts can be divided into two groups
If the built-in notifiers are not enough and you need to make something custom,
Humio supports webhooks that allow you to call an external service with HTTP.
You can add headers and [customize body of the message]({{< ref "#templates" >}}) as seen below.

* Single events, that can affect one or more users experience with the product. Usually not something that should wake up engineers at night but could result in an ticket on your issue tracker.
* Faulty state is when one or more components has reached a bad state and is unable to function properly. This usually affects most users and is something that should wake up engineers at night.
{{% /notice %}}
### Message Templates {#templates}

### Creating new alerts
The easiest way to create a new alert is by building up your query in the Search view. Don't forget to set a Live time window for the search. And then hit the Save As… → Alerts option on the right.
The Alert should have a name assigned, i.e. "Too many Internal Server Errors". Select a notifier and finally Notification Frequency. The Notification Frequency is the minimum time before the same alert will be triggered again.
Notifier templates are used to create the message sent by notifiers.
They currently apply to [Email](email.md) and [WebHook](webhook.md) notifiers.
The template engine is a simple "search/replace" model, where the `{…}` marked
placeholders are replaced with contextual aware variables.

{{% notice tip %}}
For notifiers like E-mail and Slack you want a lower Notification Frequency (more time in-between) triggers since they don't do de-duplication.
{{% /notice%}}
See the list for an explanation of the placeholders:

<!--TODO: When Auto-cancel has been implemented, please reconsider guideline on Notification Frequency -->
| Placeholder | Description |
|-------------------------------|------------------------------------------------------------|
| `{alert_name}` | The user made name of the alert fired. |
| `{alert_description}` | A user made description of the alert fired. |
| `{alert_triggered_timestamp}` | The time at which the alert was triggered. |
| `{event_count}` | The number of events in the query result. |
| `{url}` | A URL to open Humio with the alert's query. |
| `{query_string}` | The query that triggered the alert. |
| `{query_result_summary}` | A summary of data in the query result. |
| `{query_time_interval}` | The time interval for the alert's query. (e.g. 10m -> now) |
| `{warnings}` | Any warnings that was generated by the query. |

This file was deleted.

Oops, something went wrong.
@@ -6,7 +6,7 @@ weight: 500
This page provides information about the HTTP API for managing
on-premises installations of Humio.

All requests require **root-level access**. See [API token for local root access]({{< relref "login.md#root-token" >}}).
All requests require **root-level access**. See [API token for local root access]({{< relref "authentication.md#root-token" >}}).

Note, this API is still very much _work-in-progress_.

@@ -199,7 +199,7 @@ matching its tags. If no data source with the exact tags exists it is created.
Tags are used as query boundaries when searching
Tags are provided as a JSON object containing key-value pairs. Keys and values
must be strings, and at least one tag must be specified.
See the [Glossary]({{< relref "glossary.md#tags" >}}) for more information.
See the [tags documentation]({{< ref "tags.md" >}}) for more information.

#### Events

@@ -87,7 +87,7 @@ Name | Type | Required | Description
`dateTimeFields` | Array | Yes | Specifies the fields which contain the timestamp of the event. <br /><br />You can specify multiple fields, for example, a date field and a time field. The values of these fields are concatenated with whitespaces. <br /> <br /> Humio parses these fields with the format that you specify in the `dateTimeFormat` attribute.
`dateTimeFormat` | String | No | The format string that Humio should use to parse the fields identified by the `dateTimeFields` attribute. <br /><br />This attribute uses the [Java DateTimeFormatter syntax](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html). <br /><br />The default value is the ISO-8601 format, for example, `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, with milliseconds as an optional addition.
`timezone` | String | No | This field is only used if the timestamp of the event is in localtime and does not have a timezone. <br /> <br />In that case, you can use it to set a timezone. <br /><br />Do not use this field if the timezone is part of the `dateTimeFormat`.<br /><br /> Examples: `UTC`, `Z`, or `Europe/Copenhagen`.
`tagFields` |Array | No | Specify fields in events generated by this parser that should be turned into [tags]({{< relref "glossary.md#tags" >}}).<br/> For example it could be specified that the host field in the events from this parser should be treated as a tag.
`tagFields` |Array | No | Specify fields in events generated by this parser that should be turned into [tags]({{< ref "tags.md" >}}).<br/> For example it could be specified that the host field in the events from this parser should be treated as a tag.


**Response**
@@ -6,7 +6,7 @@ weight: 7
### What happened to "Dataspaces"

"Repository" is the new term. What used to be a "dataspace" in Humio is
now a [Repository]({{< relref "getting-started/repositories.md" >}}).
now a [Repository]({{< relref "using-humio/repositories.md" >}}).

The HTTP API includes the path `/api/v1/dataspaces/$REPOSITORY_NAME/` to be
compatible with existing clients.
Oops, something went wrong.

0 comments on commit c2e8ebb

Please sign in to comment.