> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronosphere.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Use annotations with monitors

*Annotations* provide runbook summaries, descriptions, and other text context for
on-call engineers diagnosing issues. Use the separate
[Links](/investigate/alerts/monitors/annotation-links) section in the monitor editor
to add templated URLs to dashboards, Logs Explorer, and external resources.

You can also add link-valued annotations through
[Terraform](/tooling/infrastructure/terraform), [Chronoctl](/tooling/chronoctl), or the API.
For cross-telemetry linking patterns, see
[Create links to related information](/investigate/querying/create-links).

Annotation values support two interchangeable forms: shorthand such as `$value`
and `$labels.LABEL`, and the equivalent Go template form such as `{{ .Value }}` and
`{{ .Labels.LABEL }}`. Use `{{ .CommonLabels.LABEL }}` to reference a monitor label,
and `{{ .Labels.LABEL }}` to reference a label from the alerting metric. Replace
*`LABEL`* with the label name.

<Note>
  Labels referenced in a variable must be present in the alerting time series. If a
  label is absent, the variable renders as empty in notifications.
</Note>

Chronosphere Observability Platform provides these annotation variables:

| Shorthand               | Go template                   | Description                                                                                                |
| ----------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `$value`                | `{{ .Value }}`                | The numeric query result value at the time the alert triggered.                                            |
| `$labels.LABEL`         | `{{ .Labels.LABEL }}`         | A label from the alerting time series. Replace *`LABEL`* with the label name.                              |
| `$externalLabels.LABEL` | `{{ .ExternalLabels.LABEL }}` | A system-level external label configured in Observability Platform. Replace *`LABEL`* with the label name. |
| `$externalURL`          | `{{ .ExternalURL }}`          | The base URL of your Observability Platform instance.                                                      |
| `$startTime`            | `{{ .StartTime }}`            | The time the alert started firing.                                                                         |
| `$endTime`              | `{{ .EndTime }}`              | The time the alert resolved.                                                                               |

Use shorthand syntax to reference label names that contain dots, such as `label.name`.
You can also use the `humanize` template function to format numeric values. For
example, `{{ $value | humanize }}` renders `1500000` as `1.5M`.

For a reference list of alerting variables and templating functions, see the
[Alertmanager documentation](https://prometheus.io/docs/alerting/latest/notifications/).

Annotation values support Markdown formatting, including bold text
(`**text**`), inline code (`` `code` ``), named links (`[label](url)`), and
plain HTTP URLs.

Annotation values can also span multiple lines using the multiline annotation
input. Each paragraph break renders as a new line in the monitor details view.

## Add annotations to a monitor

<Tabs>
  <Tab title="Web" id="use-monitor-annotations-web">
    To add annotations to a monitor:

    1. [Create a monitor](/investigate/alerts/monitors#create-a-monitor).
    2. In the **Annotations** section, add a description for your annotation in the
       **Key** field, and text or links in the **Value** field. For example, you might
       add the following key/value pairs as annotations:

       | Key         | Value                                                                                                                     |
       | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
       | summary     | Instance `{{ $labels.instance }}` is down                                                                                 |
       | description | Container `{{ $labels.namespace }}`/`{{ $labels.pod }}`/`{{ $labels.container }}` terminated with `{{ $labels.reason }}`. |
       | value       | Current value: `{{ $value }}`                                                                                             |
       | runbook     | `http://default-runbook`                                                                                                  |

       With Markdown formatting enabled, annotation values support richer formatting.
       For example, a `description` value might look like:

       ```text wrap theme={null}
       **Pod down**: `{{ $labels.namespace }}/{{ $labels.pod }}` terminated
       with reason `{{ $labels.reason }}`. See the
       [runbook](https://runbooks.example.com/pod-down) for remediation steps.
       ```
  </Tab>

  <Tab title="Chronoctl" id="use-monitor-annotations-chronoctl">
    To add annotations to a monitor with [Chronoctl](/tooling/chronoctl):

    1. Define the resource definition for your monitor, and add an `annotations` section:

       ```yaml Chronoctl example icon="square-terminal" theme={null}
       api_version: v1/config
       kind: Monitor
       spec:
         # Required name of the monitor. Can be modified after the monitor is created.
         name: Instance is down
         # PromQL query. If set, you can't set graphite_query.
         prometheus_query: up{env="prod", instance="kubernetes", exported_job="JOB123"} ==0
         # Annotations are visible in notifications generated by this monitor.
         # You can template annotations with labels from notifications.
         annotations:
           summary: 'Instance {{ $labels.instance }} is down'
           description: 'Container {{ $labels.namespace }}/{{ $labels.pod }}/{{ $labels.container }} terminated with {{ $labels.reason }}.'
           value: 'Current value: {{ $value }}'
           runbook: 'http://default-runbook'
       ```

    2. Apply the changes:

       ```shell /FILE_NAME/ theme={null}
       chronoctl apply -f FILE_NAME
       ```

       Replace *`FILE_NAME`* with the name of your monitor YAML file.
  </Tab>

  <Tab title="Terraform" id="use-monitor-annotations-terraform">
    To add annotations to a monitor with [Terraform](/tooling/infrastructure/terraform):

    1. Create a monitor with Terraform by using the `chronosphere_monitor` type followed
       by a name in a resource declaration:

       ```terraform Terraform example icon="square-terminal" theme={null}
       resource "chronosphere_monitor" "instance_down" {
         name = "Instance down"

         # Reference to the collection the alert belongs to
         collection_id = chronosphere_collection.infra.id

         # Override the notification policy.
         # By default, uses the policy from the previously stated collection_id.
         notification_policy_id = chronosphere_collection.infra_testing.id

         # Arbitrary set of labels to assign to the alert
         labels = {
           "priority" = "sev-1"
         }

         # Arbitrary set of annotations to include in alert notifications
         annotations = {
           summary     = "Instance {{ $labels.instance }} is down"
           description = "Container {{ $labels.namespace }}/{{ $labels.pod }}/{{ $labels.container }} terminated with {{ $labels.reason }}."
           value       = "Current value: {{ $value }}"
           runbook     = "http://default-runbook"
         }
       ...
       }
       ```

    2. In the `annotations` section, define the annotations for your monitor.

    3. Run `terraform apply` to create the monitor resource:

       ```shell theme={null}
       terraform apply
       ```
  </Tab>
</Tabs>