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

# Use annotations with monitors

> Add text annotations and template variables to monitors so notifications and detail pages give on-call engineers context.

*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.

Palo Alto Networks Cortex XCOR also supports link-valued annotations through
[Terraform](/tooling/infrastructure/terraform), [Chronoctl](/tooling/chronoctl), or the
Cortex XCOR 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>

Cortex XCOR 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 Cortex XCOR. Replace *`LABEL`* with the label name. |
| `$externalURL` | `{{ .ExternalURL }}` | The base URL of your Cortex XCOR 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>


## Related topics

- [Monitor data model](/investigate/alerts/monitors/data-model.md)
- [Use monitors to generate alerts and notifications](/investigate/alerts/monitors.md)
- [Discover Kubernetes scrape targets with the CXDOT Collector](/ingest/xcor/collector/discover/kubernetes.md)
- [Annotations](/ingest/pipeline/v2/configure/kubernetes/annotations.md)
- [Add templated links to monitors](/investigate/alerts/monitors/annotation-links.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.