CloudWatch Metrics Reference

UDP Gateway can publish custom Amazon CloudWatch metrics into your AWS account for both Listeners and Destinations. Listener metrics surface protocol traffic such as handshakes and keepalives; destination metrics measure application traffic. This reference explains how to configure and interpret both.

Enable Metrics and Grant Permissions

MetricsEnabled is optional and defaults to false. Set it to true at either or both levels:

• Listener: Set Properties.MetricsEnabled and supply Properties.Role, the listener's observability role.
• Destination: Set MetricsEnabled on that destination and grant metric publishing permission to its own Role, alongside its delivery permissions.

These switches are independent: enabling a listener does not enable its destinations, and enabling a destination does not enable its listener. Listener metrics are not a roll-up of destination metrics. A listener role is required when listener metrics are enabled or a listener LogGroupName is set. Use Role.Arn for the IAM role ARN at both levels.

IAM Permission

Add this statement to each role that publishes metrics. CloudWatch's PutMetricData action requires Resource: "*"; the namespace condition restricts where the role can publish:

{
  "Effect": "Allow",
  "Action": "cloudwatch:PutMetricData",
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "cloudwatch:namespace": "Proxylity/UDP Gateway"
    }
  }
}

The role must also trust Proxylity to assume it. Use your account's configured Proxylity trust policy; see Access & Permissions. The listener observability role does not need destination delivery permissions. The destination role still needs permissions such as sqs:SendMessage for its target resource.

Metrics do not require LogGroupName. Logging is separately enabled by that property and requires an existing log group plus logs:CreateLogStream and logs:PutLogEvents permissions on its log streams. Disabling metrics does not disable configured logging. AWS custom metric and alarm charges may apply; see CloudWatch pricing.

CloudFormation Example: Enable Both Levels

This template uses existing IAM roles and an existing SQS queue. Supply your Service Token and API key, a trusted client CIDR, and role ARNs. Both roles need the metric permission above; the destination role also needs SQS delivery permissions. The DTLS listener illustrates transport-level metrics alongside destination traffic metrics.

AWSTemplateFormatVersion: '2010-09-09'
Parameters:
  ServiceToken:
    Type: String
  ApiKey:
    Type: String
    NoEcho: true
  ClientCidr:
    Type: String
    Description: Trusted client network in CIDR notation
  ListenerObservabilityRoleArn:
    Type: String
  DestinationRoleArn:
    Type: String
  QueueArn:
    Type: String
Resources:
  Listener:
    Type: Custom::ProxylityUdpGatewayListener
    Properties:
      ServiceToken: !Ref ServiceToken
      ApiKey: !Ref ApiKey
      Protocols: [dtls]
      MetricsEnabled: true
      Role:
        Arn: !Ref ListenerObservabilityRoleArn
      ClientRestrictions:
        Networks:
          - !Ref ClientCidr
      Destinations:
        - Name: metrics-example-queue
          DestinationArn: !Ref QueueArn
          MetricsEnabled: true
          Role:
            Arn: !Ref DestinationRoleArn

For property details, see the Listener, Destination, and Role references.

Namespace, Dimensions, and Regions

The exact, case-sensitive namespace is Proxylity/UDP Gateway (including the space). Every metric has exactly one of these dimensions:

Use the resource's actual name, not its ARN, port, domain, or template logical ID. You can find generated names in the Proxylity dashboard. There are no combined listener-and-destination dimensions or dimensionless account totals. A shared destination aggregates its recorded traffic from all attached listeners.

CloudWatch metrics are regional. Listener metrics are published in the region of the gateway instance processing the traffic. Destination metrics use the resolved destination ARN's region, falling back to the gateway region when the ARN has no region. For multi-region deployments, inspect each relevant region rather than assuming that all metrics appear in the CloudFormation stack's region.

Metric Names and Meanings

Both scopes publish the same seven metric names when telemetry is available. Their traffic boundaries differ as described below.

Counting Rules and Traffic Boundaries

Packet Counts Are Size-Weighted

The three *Packets metrics are not raw datagram counts. Each recorded packet contributes max(1, ceil(recorded byte length / 1024)) units. For example, lengths of 100, 1023, 1024, 1025, and 2048 bytes contribute 1, 1, 1, 2, and 2 units respectively. An empty packet contributes one unit and zero bytes. The *Bytes metrics add the recorded byte lengths directly. Do not use the packet metrics as literal packet-per-second measurements.

Destination Boundaries

Ingress means accepted into the delivery queue, not confirmed delivery to the AWS service. Filtered traffic is excluded from that destination's ingress. A packet fanned out to two destinations can count toward both destinations, so summing them does not produce unique listener traffic.

Destination ingress and filtered byte accounting currently use the original incoming UDP payload length. For encrypted transports, this may include transport overhead even though the delivered application payload is decrypted or decapsulated. Egress uses the reply payload length before transport encoding. These are not Ethernet/IP wire-byte measurements or JSON/base64 request sizes.

A one-way destination such as SQS does not generate response packets, so zero destination egress is expected even while packets are being delivered successfully. Batching does not turn these counters into AWS API call counts; no batch-count metric is currently published.

Listener Protocol Traffic

Listener counters expose protocol traffic that does not appear in destination application metrics. They intentionally exclude packets carrying application data delivered to destinations and ordinary application replies. This keeps handshake and control costs visible without counting application traffic again at the listener level:

• DTLS and WireGuard handshakes, keepalives, and other protocol-only exchanges count toward listener ingress and egress, even when no application packet is delivered.
• WebRTC ICE checks and consent, DTLS handshakes, and SCTP control-only datagrams count as listener traffic. Datagrams containing SCTP DATA are excluded, including DATA bundled with control chunks. A control-only response to an application packet counts as listener egress.
• Packet Source deliveries are application traffic and are not included in listener or destination metrics.

Listener byte lengths include transport encryption overhead for protocol packets. Sending a packet is not proof that a remote client received it.

FilteredPackets and FilteredBytes measure destination BREX filtering only. They do not measure listener Client Restrictions, firewall drops, invalid transport packets, or every packet that failed to reach a destination.

Errors and Logs

Error metrics and CloudWatch Logs can be enabled independently. Reported errors contribute to Errors even when LogGroupName is not configured. A logged error contributes one occurrence, which may describe a failure affecting multiple packets or a batch. Configure logs for diagnostic details and combine gateway metrics with the AWS destination service's own metrics for end-to-end monitoring.

Charts, Alarms, and Troubleshooting

The gateway collects telemetry in roughly 10-second reporting intervals and publishes interval totals, not lifetime counters. These are standard-resolution CloudWatch custom metrics, not high-resolution metrics. Use Sum with periods of 60 seconds or longer for traffic and error totals. Average averages submitted interval samples; it does not give total traffic. To calculate bytes per second, divide the byte metric's period Sum by the period length in seconds.

Only resources with telemetry in an interval are published. An active resource's seven metrics can contain zeros, but an idle resource does not receive a continuous stream of zero samples. Metrics may not appear until a recorded event occurs. Configure alarm missing-data handling deliberately; absence of data is not automatically evidence of healthy or unhealthy traffic.

In the CloudWatch console, select the appropriate account and region, then open Metrics > All metrics > Proxylity/UDP Gateway. Select the Listener or Destination dimension and the actual resource name.

Example Alarm

This CloudFormation resource snippet alarms on any counted error for one destination over five minutes. Replace metrics-example-queue with its actual name and deploy in the metric's region. Add AlarmActions with your SNS topic ARN if you want notifications. The alarm measures error occurrences, not the number of affected packets.

DestinationRecordedErrors:
  Type: AWS::CloudWatch::Alarm
  Properties:
    AlarmDescription: UDP Gateway reported errors for this destination
    Namespace: Proxylity/UDP Gateway
    MetricName: Errors
    Dimensions:
      - Name: Destination
        Value: metrics-example-queue
    Statistic: Sum
    Period: 300
    EvaluationPeriods: 1
    Threshold: 0
    ComparisonOperator: GreaterThanThreshold
    TreatMissingData: notBreaching

For a listener alarm, change the dimension name to Listener and use the listener's actual name. Do not omit the dimension or add extra dimensions: those identify different metric series.

If Metrics Are Missing

• Check MetricsEnabled on the specific listener or destination, not only its parent or child.
• Verify that the correct role is configured, can be assumed by Proxylity, and grants cloudwatch:PutMetricData for the exact namespace.
• Check the AWS account, region, dimension name, and actual resource name.
• Generate traffic on a recorded path, allow time for publication, and use a chart period of at least 60 seconds.
• Consult observability logs, when configured and available, for role or delivery failures.