Skip to content

Commit

Permalink
docs: IncidentState type, .GetIncidentState, and new fields
Browse files Browse the repository at this point in the history
  • Loading branch information
@kylebrandt
kylebrandt committed Oct 3, 2018
1 parent 1574dfa commit c337957
Showing 1 changed file with 116 additions and 4 deletions.
120 changes: 116 additions & 4 deletions docs/definitions.md
View file
Expand Up @@ -677,13 +677,22 @@ The value of is `IsEmail` is true if the template is being rendered for an email

#### .LastAbnormalTime
{: .var}
`.LastAbnormalTime` is an int64 representing the time of `.LastAbnormalStatus`. This is not a time.Time object, but rather a unix epoch. This will be 0 when using Bosun's testing UI.

`.LastAbnormalTime` is a time.Time object that will json marshall itself as Unix time. It represents the time of `.LastAbnormalStatus`.

#### .NeedAck
{: .var}
`.NeedAck` is a boolean value that is true if the alert has not been acknowledged yet.

#### .Open
{: .var}
`.Open` is a boolean value that is true if the alert has not been closed yet.

#### .PreviousIds

`.PerviousIds` is a slice of Incident IDs (int64) that exist for the alertkey (Alert Name + TagSet) of the incident ordered with the most recent previous incident first. This can be useful to generate links to previous incidents or to get information about previous incidents using the context-bound [`.GetIncidentState` template function](/definitions#getincidentstateid-int64-incidentstate).

In Bosun's testing UI this will be populated by the previous Incidents of a real incident if you set the incident number in the interface to match a real incident id.

#### .Result
{: .var}
`.Result` is a pointer to a "result object". This is *not* the same as the [result object](/definitions#result-1) i.e. the object return by `.Eval`. Rather is has the following properties:
Expand Down Expand Up @@ -827,7 +836,7 @@ alert AzureResourceLink.Example {
}
```

#### .AzureResourceTags(prefix, rType, rsg, name string) (map[string]string)
##### .AzureResourceTags(prefix, rType, rsg, name string) (map[string]string)
{: .func}

`.AzureResourceTags` returns the Azure tags associated with the resource as a map. `prefix` identifies the subscription, an empty string as a value is the same as "default". `rType` is the resource type, `rsg` is the name of the resource group, and `name` is the name of the resource.
Expand Down Expand Up @@ -900,7 +909,7 @@ template test {
##### .ESQuery(indexRoot expr.ESIndexer, filter expr.ESQuery, sduration, eduration string, size int) ([]interface{})
{: .func}

`.ESQuery` returns a slice of elastic documents. The function behaves like the escount and esstat [elastic expression functions](/expressions#elastic-query-functions) but returns documents instead of statistics about those documents. The number of documents is limited to the provided size argument. Each item in the slice is the a document that has been marshaled to a golang interface{}. This means the contents are dynamic like elastic documents. If there is an error, than nil is returned and `.Errors` is appended to.
`.ESQuery` returns a slice of elastic documents. The function behaves like the escount and esstat [elastic expression functions](/expressions#elastic-query-functions) but returns documents instead of statistics about those documents. The number of documents is limited to the provided size argument. Each item in the slice is the a document that has been marshaled to a golang interface{}. This means the contents are dynamic like elastic documents. If there is an error, then nil is returned and `.Errors` is appended to.

The group (aka tags) of the alert is used to further filter the results. This is implemented by taking each key/value pair in the alert, and adding them as an [elastic term query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-term-query.html).

Expand Down Expand Up @@ -1196,6 +1205,86 @@ template graph {

A map of tags keys to their corresponding values for the alert.

##### .GetIncidentState(id int64) (IncidentState)
{: .func}

`.GetIncidentState` returns an [IncidentState Object](/definitions#incidentstate) for the given incident id. If there is no incident for the Id or there is an error then nil is returned and `.Errors` is appended to.

Example:

```
template previous.incidents {
<style>
td, th {
padding-right: 10px;
padding-left: 2px;
border: 1px solid black;
}
</style>
<h3>Previous Incidents with Ack/Close/Note Actions</h3>
<table>
<thead>
<tr>
<th colspan="3">Incident</th>
<th colspan="4">Actions</th>
</tr>
<tr>
<th>Id</th>
<th>Duration</th>
<th>Event Count</th>
<th>Who</th>
<th>Action</th>
<th>When</th>
<th>Message</th>
</tr>
</thead>
{{- range $id := .PreviousIds -}}
{{- $pi := $.GetIncidentState $id -}}
{{- if notNil $pi -}}
{{- $filteredActions := makeSlice -}}
{{- $incidentDuration := $pi.End.Sub $pi.Start -}}
{{- range $action := $pi.Actions -}}
{{- $actionString := $action.Type.String -}}
{{- $closed := eq $actionString "Closed" -}}
{{- $ackd := eq $actionString "Acknowledged" -}}
{{- $note := eq $actionString "Note" -}}
{{- if or $closed $ackd $note }}
{{- $filteredActions = append $filteredActions $action -}}
{{- end -}}
{{- end -}}
<tr>
{{ $actionLen := len $filteredActions }}
<td {{ if gt $actionLen 1 -}} rowspan="{{- len $filteredActions }}" {{- end -}}>
<a target="_blank" href="https://bosun.ds.stackexchange.com/incident?id={{$pi.Id}}">#{{$pi.Id }}</a>
</td>
<td {{ if gt $actionLen 1 -}} rowspan="{{- len $filteredActions }}" {{- end -}}>
{{ $incidentDuration.Truncate 1e9 }}
</td>
<td {{ if gt $actionLen 1 -}} rowspan="{{- len $filteredActions }}" {{- end -}}>
{{ len $pi.Events }}
</td>
{{- range $ia, $action := $filteredActions -}}
{{- if gt $ia 0 -}}</tr><tr></td>{{ end }}
<td>{{ $action.User }}</td>
<td>{{ $action.Type | printf "%s" }}</td>
<td>{{ $action.Time.Format "2006-01-02 15:04" }}</td>
<td>{{ $action.Message }}</td>
{{ if gt $ia 0 }}</tr>{{ end }}
{{- end -}}
</tr>
{{- else -}}
<tr><td rowspan=7>{{ .LastError }}</td></tr>
{{- end -}}
{{- end -}}
</table>
`
}
```

##### .HTTPGet(url string) string
{: .func}

Expand Down Expand Up @@ -1673,6 +1762,29 @@ There is a third property **Computations**. But it is not recommended that you a

A `.Expr` is a bosun expression. Although various properties and methods are attached to it, it should only be used for printing (to see the underlying text) and for passing it to function that evaluate expressions such as [`.Eval`](/definitions#evalstringexpression-resultvalue) within templates.

#### IncidentState
{: type}

An `IncidentState` is the main object that contains information about an incident. The IncidentState is always embedded into a template's context making these fields available context-bound template variables (Read: All IncidentState fields are available as template variables, but not all template variables are available as IncidentState fields (IncidentState is a strict/proper subset of Template Variables: `IncidentState ⊊ TemplateVars`)).

This type is also returned by [`.GetIncidentState` template function](/definitions#getincidentstateid-int64-incidentstate). The following fields are available:

* `Id`: The Id of the incident as int64
* `Start`: a [time.Time](https://golang.org/pkg/time/#Time) object, see [Template Variables `.Start`](/definitons#start)
* `End`: a pointer to a time.Time object, will be a nil pointer if the incident has not ended yet
* `AlertKey`: see [Template Variables .AlertKey](/definitions#alertkey)
* `Alert`: string representation of AlertKey
* `Result`: A pointer to an embedded [`Result` type](/definitions#result-1)
* `Events`: a slice of [Event objects](/definitions#event), see [Template Variables `.Events`](/definitons#events)
* `Actions`: a slice of [Action objects](/definitions#action), see [Template Variables `.Events`](/definitons#actions)
* `Subject`: string representation of the subject of the alert, see [Template Variables `.Events`](/definitions#subject-1)
* `NeedAck`, `Open`, `Unevaluated`: are all bool fields. See [Template Variable `.NeedAck`](/definitions#needack), [Template Variable Open](/definitions#open), and [Template Variable `.Unevaluated`](/definitions#unevaulated)
* `CurrentStatus`, `WorstStatus`, `LastAbnormalStatus` are all [`Status` objects](/definitions#status). See See [Template Variable `.CurrentStatus`](/definitions#currentstatus), [Template Variable `.WorstStatus`](/definitions#worststatus), and [Template Variable `.LastAbnormalStatus`](/definitions#lastabnormalstatus)
* `LastAbnormalTime` is time.Time object that will marshall itself as Unix time. See [Template Variable `.LastAbnormalTime`](/definitions#lastabnormaltime)
* `PreviousIds` is a slice of Incident IDs (int64) of previous Incidents. See [Template Variable `.LastAbnormalTime`](/definitions#previousids)
* `NextId` is the ID of a future incident for the same AlertKey. If there is no future incident, then the value is 0.
* `Notifications` is a string slice of all notifications names that were sent for the incident at the present time.

#### Result
{: .type}

Expand Down

0 comments on commit c337957

Please sign in to comment.