AWS CloudWatch - aciona.me

Overview

CloudWatch publishes alarm transitions to an SNS topic. A Lambda subscribed to that topic converts the notification into aciona.me’s canonical format and posts it to the alert source.


Source type	`CloudWatch`
Mechanism	SNS + Lambda
Correlation	`alarmArn`
Auto-resolution	✅ (requires `OKActions`)

Prerequisites

AWS permission to create SNS topics, Lambda functions and modify alarms.
A service created in aciona.me and linked to a team with an active schedule.

1. Create the alert source in aciona.me

Under Alert sources, create a source of type CloudWatch. Copy the URL and the token.

aws sns create-topic --name aciona-me-cloudwatch

3. Deploy the transform Lambda

Runtime Node.js 20+, handler index.handler, no external dependencies. Environment variables:

Variable	Value
`ACIONA_INGRESS_URL`	`https://ingress.aciona.me/webhooks/<alertSourceId>`
`ACIONA_TOKEN`	The source token
`REGION`	The Lambda’s region, e.g. `us-east-1`

IAM role: AWSLambdaBasicExecutionRole.

In production, keep the token in SSM Parameter Store (SecureString) or Secrets Manager and read it on cold start — do not leave the value in plain text in the Lambda configuration.

Lambda code

index.mjs

import https from 'node:https';
import { URL } from 'node:url';

const SEVERITY_MAP = {
  crit: 'critical', critical: 'critical', sev1: 'critical', p1: 'critical',
  high: 'high', sev2: 'high', p2: 'high',
  warn: 'warning', warning: 'warning', sev3: 'warning', p3: 'warning',
  info: 'info', low: 'info', sev4: 'info', p4: 'info',
};

const str = (v) => (v === null || v === undefined ? '' : String(v));

function parseRegionFromArn(arn) {
  const parts = str(arn).split(':');
  return parts.length >= 4 ? parts[3] : '';
}

function resolveSeverity(alarmDescription, alarmName) {
  const m = str(alarmDescription).match(/\[severity:([a-zA-Z0-9]+)\]/);
  if (m) return SEVERITY_MAP[m[1].toLowerCase()] || 'warning';
  const name = str(alarmName).toLowerCase();
  for (const k of ['critical', 'high', 'warning', 'info']) {
    if (name.includes(k)) return k;
  }
  return 'warning';
}

function extractServiceHint(trigger, alarmName) {
  if (!trigger || typeof trigger !== 'object') return str(alarmName);
  const dims = trigger.Dimensions || {};
  const byNamespace = {
    'AWS/ECS': ['ServiceName', 'ClusterName'],
    'AWS/RDS': ['DBClusterIdentifier', 'DBInstanceIdentifier'],
    'AWS/DynamoDB': ['TableName'],
    'AWS/Lambda': ['FunctionName'],
    'AWS/EC2': ['InstanceId'],
    'AWS/ApplicationElb': ['LoadBalancer'],
    'AWS/ApiGateway': ['ApiName'],
    'AWS/SQS': ['QueueName'],
    'AWS/S3': ['BucketName'],
  };
  for (const k of byNamespace[trigger.Namespace] || []) {
    if (dims[k]) return str(dims[k]);
  }
  const ns = str(trigger.Namespace).replace(/^(AWS\/|ECS\/|EKS\/)/, '');
  return ns || str(alarmName);
}

function toCanonical(msg) {
  const alarmArn = str(msg.AlarmArn);
  const alarmName = str(msg.AlarmName);
  const region = parseRegionFromArn(alarmArn) || process.env.REGION || '';
  const trigger = msg.Trigger || null;
  return {
    schema: 'aciona.cloudwatch.v1',
    source: 'aws_cloudwatch',
    alarmName,
    alarmArn,
    awsAccountId: str(msg.AWSAccountId),
    region,
    state: str(msg.NewStateValue).toUpperCase(),
    oldState: str(msg.OldStateValue).toUpperCase(),
    reason: str(msg.NewStateReason),
    stateChangeTime: str(msg.StateChangeTime),
    severity: resolveSeverity(msg.AlarmDescription, alarmName),
    service: extractServiceHint(trigger, alarmName),
    dimensions: trigger?.Dimensions || null,
    trigger: trigger
      ? {
          metricName: trigger.MetricName,
          namespace: trigger.Namespace,
          statistic: trigger.Statistic,
          period: trigger.Period,
          evaluationPeriods: trigger.EvaluationPeriods,
          comparisonOperator: trigger.ComparisonOperator,
          threshold: trigger.Threshold,
        }
      : null,
    alarmDescription: str(msg.AlarmDescription),
    url: region && alarmName
      ? `https://console.aws.amazon.com/cloudwatch/home?region=${region}#alarmsAlarm:alarmName=${encodeURIComponent(alarmName)}`
      : '',
  };
}

function postToIngress(payload) {
  return new Promise((resolve, reject) => {
    const url = new URL(process.env.ACIONA_INGRESS_URL);
    const body = JSON.stringify(payload);
    const req = https.request(
      {
        method: 'POST',
        hostname: url.hostname,
        path: url.pathname + url.search,
        headers: {
          'Content-Type': 'application/json',
          'Content-Length': Buffer.byteLength(body),
          'X-Aciona-Token': process.env.ACIONA_TOKEN,
        },
      },
      (res) => {
        let data = '';
        res.on('data', (c) => (data += c));
        res.on('end', () => {
          if (res.statusCode >= 200 && res.statusCode < 300) resolve(data);
          else reject(new Error(`HTTP ${res.statusCode}: ${data}`));
        });
      },
    );
    req.on('error', reject);
    req.write(body);
    req.end();
  });
}

export const handler = async (event) => {
  const results = [];
  for (const record of event.Records || []) {
    try {
      const canonical = toCanonical(JSON.parse(record.Sns.Message));
      await postToIngress(canonical);
      results.push({ ok: true, alarmArn: canonical.alarmArn });
    } catch (err) {
      console.error('[aciona.me] SNS record failed', err.message);
      results.push({ ok: false, error: err.message });
    }
  }
  if (results.length > 0 && results.every((r) => !r.ok)) {
    throw new Error('All records failed');
  }
  return { batch: results };
};

aws sns subscribe \
  --topic-arn <topic-arn> \
  --protocol lambda \
  --notification-endpoint <lambda-arn>

Harden the topic policy with aws:SourceAccount and, where possible, aws:SourceArn, so only CloudWatch in your account can publish.

5. Configure the alarm with AlarmActions and OKActions

aws cloudwatch put-metric-alarm \
  --alarm-name "payments-api-5xx-high" \
  --alarm-description "5xx above 5/s for 1 minute [severity:critical]" \
  --alarm-actions <topic-arn> \
  --ok-actions <topic-arn> \
  ...

OKActions is required for auto-resolution. Without it, CloudWatch never emits the OK transition and the incident stays open indefinitely. This is the most-forgotten step in the whole integration.

6. Test

aws cloudwatch set-alarm-state \
  --alarm-name "payments-api-5xx-high" \
  --state-value ALARM \
  --state-reason "aciona.me manual test"

Confirm the incident in the dashboard. Then force the recovery:

aws cloudwatch set-alarm-state \
  --alarm-name "payments-api-5xx-high" \
  --state-value OK \
  --state-reason "aciona.me manual test"

The incident should be resolved automatically.

How fields are translated

Alarm state	Effect
`ALARM`	Creates or aggregates an incident
`OK`	Resolves automatically
`INSUFFICIENT_DATA`	Ignored

CloudWatch has no native severity. The Lambda resolves an alias in layers:

A marker in AlarmDescription: [severity:critical]
A keyword in the alarm name (critical, high, warning or info)
Default: warning

Troubleshooting

The incident opens but never closes

The alarm has no OKActions pointing at the SNS topic. Add it with put-metric-alarm --ok-actions.

Nothing arrives in aciona.me

Check, in this order: the Lambda’s subscription to the topic is confirmed; the Lambda logs in CloudWatch Logs; ACIONA_INGRESS_URL and ACIONA_TOKEN are correct; the Lambda has internet egress (inside a VPC it needs a NAT).

Wrong service on the incident

Adjust the alarm dimensions, or create a service in aciona.me matching the name the Lambda derives. See the extractServiceHint function in the code.

Severity always warning

Add [severity:critical] to the AlarmDescription or include the keyword in the alarm name.

​Overview

​Prerequisites

​1. Create the alert source in aciona.me

​2. Create the SNS topic

​3. Deploy the transform Lambda

​4. Subscribe the Lambda to the topic

​5. Configure the alarm with AlarmActions and OKActions

​6. Test

​How fields are translated

​Troubleshooting

Overview

Prerequisites

1. Create the alert source in aciona.me

2. Create the SNS topic

3. Deploy the transform Lambda

4. Subscribe the Lambda to the topic

5. Configure the alarm with AlarmActions and OKActions

6. Test

How fields are translated

Troubleshooting