ITRS Geneos to Flashduty

English | 简体中文

geneos-flashduty is a small, standalone Go executable that converts ITRS Geneos Alerting Effect or Rule Action events into Flashduty standard alert events. It runs once per event, keeps no local state, and can be deployed as a single binary on the Geneos Gateway host.

How it works

Geneos Alerting + Effect --\
                            +--> geneos-flashduty --> Flashduty Standard Alert API
Geneos Rule + Action -------/

Trigger and recovery events are correlated by a stable alert_key:

_VARIABLEPATH is present
  geneos:v1:<SHA-256(_VARIABLEPATH)>

_VARIABLEPATH is absent and stable Geneos fields are sufficient
  geneos:v1:fallback:<SHA-256(canonical-fields)>

No stable identity is available
  geneos:v1:random:<UUID v4>

The random fallback still delivers the event, but a later recovery cannot be guaranteed to match it. When _VARIABLEPATH is present, its original value is also sent as the geneos_variable_path label for diagnostics. The full value is always used for hashing even if the label must be truncated to meet protocol limits.

Status mapping

Geneos context	Flashduty event_status
_ALERT_TYPE=clear	Ok
_SEVERITY=OK	Ok
_SEVERITY=CRITICAL	Critical
_SEVERITY=WARNING	Warning
_SEVERITY=INFO or UNDEFINED	Info

The resolve command always sends Ok. Flashduty's standard event protocol has no equivalent of PagerDuty's acknowledge, so Geneos suspend and assignment events are not mapped to acknowledgement. Ownership, on-call, and escalation stay in Flashduty.

Install

Download the binary for your Gateway host from GitHub Releases, verify it against SHA256SUMS, and install it in a path available to Geneos. For example:

install -m 0755 geneos-flashduty-v1.0.0-linux-amd64 \
  /opt/itrs/gateway/gateway_shared/geneos-flashduty

To build from source, use Go 1.22 or newer:

go test ./...
go build -o geneos-flashduty ./cmd/geneos-flashduty

Configure

Copy flashduty.example.yaml to one of these locations:

1. the path passed with --config;
2. ./flashduty.yaml;
3. $HOME/.config/geneos/flashduty.yaml;
4. /etc/geneos/flashduty.yaml.

The first matching file wins. An explicit but unreadable --config path is an error; missing implicit files are ignored.

Obtain an integration key

Create a Standard Alert Event integration in Flashduty and copy its push URL. Flashduty provides two setup paths:

1. Dedicated integration — open a collaboration space, select Integration Data, click Add an integration, select Standard Alert Event, save it, then open the generated card and copy the push URL.
2. Shared integration — open Integration Center → Alert Events, select Standard Alert Event, configure its name and default route to a collaboration space, save it, and copy the generated push URL.

The URL contains the credential as a query parameter:

https://api.flashcat.cloud/event/push/alert/standard?integration_key=YOUR_KEY

Use the copied URL when configuring the program:

• set flashduty.endpoint to the copied URL with only the integration_key parameter removed; preserve its host, path, and any other query parameters, especially when they differ from the default endpoint;
• copy the integration_key value into YAML or set it through FLASHDUTY_INTEGRATION_KEY, as shown below.

The program appends the key automatically. Treat it as a secret.

See the official Standard Alert Event documentation for the latest console steps and protocol details.

Minimal configuration:

flashduty:
  endpoint: https://api.flashcat.cloud/event/push/alert/standard
  integration_key: your-integration-key

flashduty.endpoint can be changed if your Flashduty push URL changes. If it is omitted, the URL above is the compiled default. The program appends the integration key as the integration_key query parameter, including when the endpoint already has other query parameters.

For better secret handling and per-entity routing, set the key as a Geneos Managed Entity or Managed Entity Group attribute instead:

FLASHDUTY_INTEGRATION_KEY=<your-integration-key>

This environment value overrides the YAML value. Trigger and recovery events must use the same integration key; otherwise they reach different Flashduty integrations and cannot correlate even when their alert_key values match.

The example configuration also documents timeout, retry, severity, title, description, and custom-label settings. ${NAME} references in title, description, and custom label values expand from environment variables. Endpoint, key, timeout, retries, key prefix, and severity mapping are not template-expanded.

Configure Geneos

Use examples/geneos-effect.xml as the recommended Alerting Effect example, or examples/geneos-action.xml for a Rule Action.

An Alerting Effect receives Geneos lifecycle events, including _ALERT_TYPE=clear, and therefore maps recovery automatically. When using a Rule Action, configure the rule so that the action also runs when the severity returns to OK.

The executable recognizes a strict allow-list of Geneos context variables instead of sending the entire process environment. Common labels include Gateway, Probe, Managed Entity, Sampler, Dataview, row, column, rule, Geneos severity, alert type, and variable path.

Commands

Automatic Effect or Action mode:

geneos-flashduty

Force a trigger or recovery with a known variable path:

geneos-flashduty trigger --variable-path '/geneos/.../cell'
geneos-flashduty resolve --variable-path '/geneos/.../cell'

Validate configuration and test connectivity:

geneos-flashduty test --config /etc/geneos/flashduty.yaml

Test mode sends Info and then Ok with the same generated key so it does not intentionally leave an open alert.

Delivery behavior

• Per-attempt timeout defaults to 10 seconds.
• The initial request is followed by up to three retries by default.
• Network errors, HTTP 429, and HTTP 5xx are retried with exponential backoff and jitter.
• Retry-After is honored up to 60 seconds.
• Other HTTP 4xx responses are not retried.
• Success exits with code 0; validation or final delivery failure exits non-zero.
• The integration key is redacted from logs.
• Unknown environment variables are not included in the payload.

Troubleshooting

• If the program reports that an integration key is required, set FLASHDUTY_INTEGRATION_KEY or flashduty.integration_key.
• HTTP 401/403: verify that the endpoint and key belong to the same Flashduty integration.
• An alert does not recover: verify the same _VARIABLEPATH, key algorithm version, and integration key are used for both events.
• alert_key_source=random appears in logs: Geneos did not provide enough stable identity data, so recovery correlation cannot be guaranteed.
• Connection failure: confirm that the Gateway host can reach the configured endpoint over HTTPS.

Development

gofmt -w .
go test -race ./...
go vet ./...
go build ./cmd/geneos-flashduty

Version tags matching v* build Linux and macOS executables for AMD64 and ARM64, publish SHA256SUMS, and create a GitHub Release.

License

MIT