Alertmanager-jira: integration of alerts with Jira

Integrating Alertmanager with Jira: Flexible Webhook Plugin on Quarkus

Alertmanager-jira is an open-source webhook plugin for Alertmanager (Prometheus, VictoriaMetrics) that creates and manages issues in Jira. It supports assigning assignees, custom fields, description templates, and duplicate detection via JQL. Built on Quarkus, it deploys via Docker/Podman. This tool addresses the limitations of alternatives like jiralert, providing full control over tickets without custom scripts.

Issues with Existing Solutions

Jiralert from prometheus-community creates issues based on group_key, uses Go templates, and supports auto-resolution. However, in practice, it has these limitations:

• Minimal configuration: basic YAML templates, no support for custom fields or dynamic JQL queries.
• Long group_key hashes break Jira's UI.
• Slow development: open bugs since 2018, infrequent updates.

Other options include enterprise solutions like PagerDuty or custom scripts. Alertmanager-jira offers flexibility: default values for projects/issue types, overrides in alerts, and comments on existing tickets.

Deploying in a Container

The project comes with Docker images on hub.docker.com. Example launch with Podman (similar to Docker):

podman run -it --rm --name alertmanager-jira \
    --env JIRA_URL=https://your-jira.com \
    --env JIRA_USERNAME=service-account \
    --env JIRA_PASSWORD=your-token \
    -p 8080:8080 \
        hubbitus/alertmanager-jira:latest

Configuring Alertmanager

Add a receiver in alertmanager.yml:

receivers:
  - name: 'jira'
    webhook_configs:
      - url: 'http://your-host:8080'
        send_resolved: true

Configuring Alerts in Prometheus/VictoriaMetrics

Jira fields are set using the jira__ prefix in labels/annotations of rules. Groovy SimpleTemplate templates are supported.

Example prometheus-rules.yml:

groups:
- name: example
  rules:
  - alert: HighCPU
    expr: 100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 80
    for: 1m
    labels:
      severity: critical
      jira__field__severity: High
    annotations:
      summary: "High CPU on {{ $labels.instance }}"
      description: "CPU usage above 80%."
      jira__project_key: OPS
      jira__issue_type_name: Incident
      jira__field__assignee: oncall-sre
      jira__field__labels: 'monitoring, cpu, alert'
      jira__field__component_s: 'DevOps+infrastructure, DQ-issues+alerts'
      jira__field__name__1: 'Custom Field'
      jira__field__value__1: 'Some dynamic value: ${context.alert.severity}'

Default values in prometheus.yml via alert_relabel_configs:

alerting:
  alert_relabel_configs:
    - source_labels: [__alert_severity]
      target_label: jira__field__severity
      regex: critical;High
    - target_label: jira__project_key
      replacement: OPS

Overrides in specific alerts take priority. Templates:

• ${context.alert.fingerprint} — alert hash.
• ${context.jiraProject.name} — project metadata.
• JQL for searching: labels = "alert[${context.alert.hashCode()}]") AND statusCategory != Done.

Technical Implementation

Built on Java + Groovy (Quarkus), Atlassian Jira SDK. Tests: unit tests for parsing, integration tests on an external Jira instance. CI doesn't run tests due to Jira licensing restrictions — requires manual runs on a deployed server.

Possible improvements: integrate tests into CI using temporary licenses or mock servers.

Key Features

• Field flexibility: any custom fields, labels, components via jira__ prefix and templates.
• Deduplication: JQL search for existing issues with comment option.
• Automation: reduces MTTR in DevOps/SRE/ITSM via auto-tickets.
• Production-ready: 2 years in production on a data platform.
• Open-source: Apache 2.0, GitHub for issues/PRs.

— Editorial Team