CloudWatch
Floci supports both CloudWatch Logs and CloudWatch Metrics.
CloudWatch Logs
Protocol: JSON 1.1 (X-Amz-Target: Logs.*)
Endpoint: POST http://localhost:4566/
Supported Actions
| Action | Description |
|---|---|
CreateLogGroup |
Create a log group |
DeleteLogGroup |
Delete a log group |
PutLogGroupDeletionProtection |
Enable or disable deletion protection for a log group by name or ARN |
DescribeLogGroups |
List log groups |
CreateLogStream |
Create a log stream inside a log group |
DeleteLogStream |
Delete a log stream |
DescribeLogStreams |
List log streams in a group |
PutLogEvents |
Write log events to a stream |
GetLogEvents |
Read log events from a stream |
FilterLogEvents |
Search log events with a filter pattern |
PutRetentionPolicy |
Set log retention (days) |
DeleteRetentionPolicy |
Remove log retention policy |
AssociateKmsKey |
Associate a KMS key with a log group (logGroupName or resourceIdentifier) |
DisassociateKmsKey |
Remove a log group's KMS key association |
TagLogGroup |
Tag a log group |
UntagLogGroup |
Remove tags |
ListTagsLogGroup |
List tags |
TagResource |
Tag a log group, cross-account destination, delivery source, delivery destination or delivery by ARN |
UntagResource |
Remove tags from a log group, cross-account destination, delivery source, delivery destination or delivery by ARN |
ListTagsForResource |
List tags for a log group, cross-account destination, delivery source, delivery destination or delivery ARN |
PutSubscriptionFilter |
Create or update a subscription filter (see Subscription filters) |
DescribeSubscriptionFilters |
List subscription filters on a log group |
DeleteSubscriptionFilter |
Delete a subscription filter |
PutMetricFilter |
Create or replace a metric filter on a log group (see Metric filters) |
DescribeMetricFilters |
List metric filters by log group and name prefix, or by metric name and namespace |
DeleteMetricFilter |
Delete a metric filter |
TestMetricFilter |
Run a filter pattern over sample messages and return the matches with their extracted values |
PutResourcePolicy |
Create or update an account-level resource policy |
DescribeResourcePolicies |
List account-level resource policies |
PutDestination |
Create or update a cross-account subscription destination, with optional tags on creation |
PutDestinationPolicy |
Create or update the access policy for a destination |
PutAccountPolicy |
Create or update an account-level Logs policy |
DescribeAccountPolicies |
List account-level Logs policies by type and optional name |
GetDataProtectionPolicy |
Return the resolved log group identifier (see note below) |
StartQuery |
Start a Logs Insights query (see Logs Insights) |
GetQueryResults |
Get the status and results of a Logs Insights query |
StopQuery |
Stop a query that has not completed yet |
PutQueryDefinition |
Create or replace a saved Logs Insights query definition |
DescribeQueryDefinitions |
List saved queries, with name prefix and query language filters and pagination |
DeleteQueryDefinition |
Delete a saved query definition by ID |
PutDeliverySource |
Create or replace a vended-log delivery source (see Vended log delivery) |
GetDeliverySource |
Return a delivery source |
DeleteDeliverySource |
Delete a delivery source no delivery uses |
DescribeDeliverySources |
List delivery sources, optionally only those for given resource ARNs |
PutDeliveryDestination |
Create or replace a delivery destination: a log group, S3 bucket, Firehose stream or X-Ray |
GetDeliveryDestination |
Return a delivery destination |
DeleteDeliveryDestination |
Delete a delivery destination no delivery uses |
DescribeDeliveryDestinations |
List delivery destinations, optionally only those with given names |
CreateDelivery |
Pair a delivery source with a delivery destination |
GetDelivery |
Return a delivery, with its record fields and S3 configuration |
UpdateDeliveryConfiguration |
Change a delivery's record fields, delimiter or S3 configuration |
DeleteDelivery |
Delete a delivery |
DescribeDeliveries |
List deliveries, optionally only those from given delivery sources |
DescribeLogGroups returns names in ASCII order, with up to 50 groups per page by default.
Set limit to an integer from 1 to 50 and pass the returned nextToken with the same region
and name prefix to continue. The final page omits nextToken.
CreateLogGroup stores logGroupClass as STANDARD (the default), INFREQUENT_ACCESS, or
DELIVERY. DescribeLogGroups returns the stored class and applies an optional logGroupClass
filter before pagination. Continue with the same class filter when using nextToken.
Stored groups without a class default to STANDARD. Class metadata does not change retention,
delivery behavior, or the features available on a group.
Log group deletion protection defaults to disabled and is persisted with the log group. When it is
enabled, DeleteLogGroup returns ValidationException until protection is explicitly disabled
with PutLogGroupDeletionProtection.
One action is currently simplified:
GetDataProtectionPolicydoes not model data-protection policies. It returns HTTP 200 with the resolvedlogGroupIdentifierand nopolicyDocument, including for a log group that does not exist, where real AWS returnsResourceNotFoundException.
FilterLogEvents reads filterPattern with the filter pattern syntax described below, the one
metric filters and subscription filters use: terms, quoted phrases, ? alternatives, -
exclusions, JSON and space-delimited patterns. An invalid pattern is refused with
InvalidParameterException, and so is a request that names no log group by logGroupName or
logGroupIdentifier.
Saved query definitions
PutQueryDefinition, DescribeQueryDefinitions, and DeleteQueryDefinition store and manage
saved Logs Insights queries, including the metadata used by Terraform's
aws_cloudwatch_query_definition. Definitions are isolated by account and region and use the
configured CloudWatch Logs storage mode, including persistence across restarts.
Create a definition with name and queryString; pass its returned queryDefinitionId to
update it. Updates replace the definition, so omitting logGroupNames or parameters clears
those lists. queryLanguage defaults to CWLI; SQL and PPL are also stored as metadata.
Query parameters are supported for CWLI definitions. Saving a definition does not execute or
validate its query syntax, and does not extend the query execution subset described below.
Log group names can be saved before their groups exist.
clientToken retries are scoped to the account and region and retain the original request and
returned ID independently of later updates. Repeating that request returns the same ID without
overwriting newer content; reusing its token with different input returns InvalidParameterException.
Floci retains these records until emulator reset, including after the definition is deleted, so
a delayed retry cannot recreate a deleted definition. They use the same storage mode as definitions.
During reset, saves and deletes return ServiceUnavailableException until the reset hooks resume writes.
DescribeQueryDefinitions accepts queryDefinitionNamePrefix, queryLanguage, and
maxResults from 1 to 1000. Pass the returned nextToken with the same account, region, and
filters for the next page; the final page omits it. Tokens expire after 24 hours or an emulator
restart. Updating or deleting an unknown definition returns ResourceNotFoundException.
Vended log delivery
Delivery sources, delivery destinations and the deliveries that pair them, which Terraform's
aws_cloudwatch_log_delivery_source, aws_cloudwatch_log_delivery_destination and
aws_cloudwatch_log_delivery manage, for example for an EventBridge bus's logs. Floci stores the
configuration and does not deliver the source's logs.
PutDeliverySourceandPutDeliveryDestinationcreate the resource or replace every parameter of an existing one. A source reports the service of its resource's ARN (eventsfor an event bus) and thelogTypeit was given.- A destination's
deliveryDestinationTypefollows from its resource's ARN:CWLfor a log group,S3for a bucket,FHfor a Firehose stream. Only an X-Ray destination, which has no resource, names its type. CreateDeliveryneeds an existing source and destination, and one delivery per pair; a second isConflictException. Its id is 16 letters and digits. For an EventBridge event bus source,recordFieldsdefaults to the bus's ten template fields ands3DeliveryConfigurationto the{region}/{yyyy}/{MM}/{dd}/{HH}/suffix path, as AWS reports them.GetDeliveryreturns those;DescribeDeliveriesleaves them out, as AWS does.- A source or destination a delivery uses cannot be deleted (
ConflictException). - Tags are set on create and through
TagResource,UntagResourceandListTagsForResourceon the resource's ARN; the Get and Describe responses carry none, as on AWS. DescribeDeliverySourcesnarrows toresourceArns,DescribeDeliveryDestinationstonamesandDescribeDeliveriestodeliverySourceNames; a name that matches nothing is left out, not an error.- Requests are checked against the Logs API model's lengths, patterns, enums and required members,
with AWS's
ValidationExceptionwording, for example "1 validation error detected: Value at 'limit' failed to satisfy constraint: Member must have value less than or equal to 50". - An unknown name or id is
ResourceNotFoundException, "Requested Delivery Source does not exist in this account." (likewise for a Delivery Destination and a Delivery). - With IAM enforcement on, each action is authorized on the resources the AWS Service Authorization
Reference lists for it: the source, destination or delivery it names, and for
CreateDeliverythe source, the destination and the new delivery;DeleteDeliverySourceon the delivery destinations the deliveries from the source it deletes send to, the type the reference lists for it, and on*for a source with none. The Describe actions are authorized on*, as the reference lists no resource for them.
Not modelled: delivery destination policies (PutDeliveryDestinationPolicy and its siblings), and
record field defaults for sources other than an EventBridge event bus.
Subscription filters
Subscription filters deliver newly ingested log events to a downstream destination. Floci delivers
matching events to Lambda functions, Kinesis data streams, and Firehose delivery streams. Delivery
happens synchronously on the calling thread when PutLogEvents persists events. A destination error,
missing destination stream/function, or unresolvable destination ARN is logged and does not fail the
log ingestion request.
The delivered payload is a gzip-compressed JSON object containing messageType (DATA_MESSAGE),
owner (the account ID), logGroup, logStream, subscriptionFilters (the matched filter names),
and logEvents (an array of {id, timestamp, message}). Lambda receives the payload base64-encoded
under awslogs.data. Kinesis and Firehose receive the gzip-compressed JSON bytes directly as record data.
For Kinesis destinations, distribution controls the partition key: ByLogStream uses the log stream
name, while Random assigns a randomized UUID partition key. Cross-account Logs destinations
(PutDestination), IAM role permission checks, and the CONTROL_MESSAGE ping on filter creation
are deferred.
Metric filters
A metric filter turns newly ingested log events into CloudWatch metric samples. Each matching
event contributes the literal metricValue, or its referenced field ($.latency in JSON,
$size in space-delimited logs), at the event timestamp, not ingestion or filter-creation time.
Events ingested before the filter existed are not replayed. Backdated and future event timestamps
remain backdated and future metric timestamps.
A configured defaultValue contributes once per nonmatching event, including alongside matches
in the same batch or minute. A matching event with a missing or JSON-null metric-value field also
uses the default; a present nonnumeric value is skipped, not replaced by the default. Without a
default, those nonmatches and missing/null values produce no sample. No events means no samples.
Healthy publication is immediate and needs no subsequent ingestion, reads, or timer. For example,
pattern ERROR, value 3 and default 7 produce Sum 13 / SampleCount 3 for ERROR, INFO, ERROR,
and three quiet nonmatches produce Sum 21 / SampleCount 3. A late match appends its value without
retracting earlier defaults. CloudWatch aggregates these contributions by period; Floci has no
minute-default accumulator or deduplication history.
Ordinary transformation dimensions are all-or-none: a complete configured set is emitted, while
a missing member produces a dimensionless sample, not a partial set. Requested system dimensions
(@aws.account, @aws.region) are populated on matches using the resolved receiving account and
region, including regular noncentralized Logs ingestion. Pattern-nonmatch defaults are
dimensionless, even when system dimensions are requested. These scenarios are supported by the
recorded live AWS observations.
Inferred emulator policy, not a live AWS claim: matching missing/null metric-value fallbacks retain requested system dimensions. Likewise, an incomplete ordinary dimension set is discarded as a unit while requested system dimensions are retained. Null ordinary dimension values are treated as missing; empty strings retain the existing scalar-extraction behavior. These combinations were not measured by the recorded probes. Floci does not infer centralized source provenance.
Publication runs off the request thread: PutLogEvents evaluates the group's filters as they
are at that moment, builds one immutable sample per contributing event (canonical account, region,
group, filter, transformation snapshot, event timestamp and a stable internal publication ID) and
hands them to a process-wide queue. One managed worker writes them to the Metrics store, so
ingestion latency does not depend on the Metrics sink and a PutMetricFilter or a reset waits for
at most one sample write. The queue holds 100,000 samples; a batch that does not fit is written
on the request thread under the filter-store monitor instead of being dropped, so accepted samples
are never lost to the bound and only an overfull queue makes the request wait on the sink.
A read issued immediately after PutLogEvents may run before the worker has written the sample,
as on AWS; SDK tests should poll. Shutdown drains the queue before storage shuts down.
Runtime publication failures: accepted Logs ingestion remains successful if the Metrics sink
reports a failure. Each failed sample keeps its snapshot and publication ID, and retries replace
that same metric-store key, making partial or ambiguous writes safe without deduplicating distinct
identical log events. The existing AWS PutMetricData APIs continue appending samples as before.
The same worker retries failed publications at one-second intervals while both Logs and Metrics services are enabled; idle ticks never create defaults. The retry map holds at most 10,000 samples, not 10,000 batches. This fixed conservative limit bounds outage memory without introducing a configuration surface. When full, new failed samples are dropped with an ERROR containing account, region, group, filter and dropped count; already queued samples and their IDs are preserved. Successful retries and cancellations release capacity. Each filter-owned outage logs one detailed stack, followed by a stack-free aggregate warning every 60 failed retry ticks. Recovery, cancellation and reset release that suppression. This is bounded best effort, not lossless delivery through an indefinite outage. Pending work is in memory only; crash-durable pending publication is not implemented. Storage failures that a backend only logs rather than throws are not observable to this retry path; configured storage durability semantics are unchanged.
A filter update or deletion affects new ingestion only: samples already accepted for a batch still publish under the definition that was current at ingestion, as on AWS, and deleting a filter or group cancels only its own account/region-scoped failed retries without retracting stored metrics. Reset pauses publication, waits for the active sample write, discards queued and failed samples, wipes storage and resumes the same live service. The canonical filter-store monitor serializes each sample write with update/delete; reset hooks release it before the storage-factory wipe to avoid lock inversion. Shutdown writes the queued samples, abandons failed retries and stops the worker (up to five seconds to await executor termination). Storage backends expose synchronous operations without a cancellation deadline; a stuck backend can delay that drain. Runtime cancellation is not a crash-recovery guarantee.
Samples are readable with GetMetricStatistics and GetMetricData, and alarms evaluate normally.
The filter pattern syntax follows the AWS reference:
- Terms:
ERROR ARGUMENTS(all present),?ERROR ?ARGUMENTS(any present),ERROR -ARGUMENTS(exclusion),"exact phrase". Terms are case-sensitive substrings of the message. - Regular expressions between percent signs,
%^[hc]at%, with the operators and escapes AWS allows. Parentheses and characters outside ASCII are rejected, as on AWS. - JSON patterns:
{ $.eventType = "UpdateTrail" && $.code >= 400 }, with=,!=,<,<=,>,>=,IS NULL,IS TRUE,IS FALSE,NOT EXISTS,&&,||, parentheses, array indexes,[*]and.*wildcards, and$.['a.b']for a property with a dot in its name. AWS's wildcard quotas apply: one per property selector and three per pattern. - Space-delimited patterns:
[ip, ..., status_code = 4*, bytes], with named fields,...for any number of fields, conditions on any field,w1/w2indicators, and%regex%values. Text between double quotes or square brackets is one field.
PutMetricFilter applies the rules AWS applies: the log group must exist, the pattern must parse,
at most two regular expressions per pattern, exactly one transformation whose metricValue is a
number or a single-valued field reference, at most three dimensions in total, and 100 metric
filters per log group. Scalar JSON metric-value and dimension references need not be mentioned
in the filter pattern. Wildcard metric-value references such as $.values[*] are rejected;
wildcards remain available in the filter pattern itself. Ordinary dimensions are
available only for JSON or space-delimited patterns and cannot be combined with a defaultValue;
system-only dimensions can. The shared group regex quota counts up to five regex-bearing filters
across metric and subscription filters, independently of the two expressions allowed per pattern.
This shared pool is documentation-backed, not a new live mixed-writer claim. TestMetricFilter
reports one-based event numbers. JSON matches have empty public extractedValues; space-delimited
matches expose named fields as $name and positional fields as $1, $2 and so on.
fieldSelectionCriteria selects which batches a filter processes from the system fields
@aws.account and @aws.region, with =, !=, IN, NOT IN and the AND and OR the API
documents, as in @aws.account IN ["111111111111"]. Both fields describe the ingested batch rather
than the individual event, so one evaluation decides the batch. A criterion that does not parse is
rejected when the filter is stored.
emitSystemFieldDimensions adds @aws.account and @aws.region on matching contributions as
described above. They count toward the same combined limit of three dimensions.
applyOnTransformedLogs is stored and returned unchanged. Request acceptance was verified on AWS,
including true on the tested group without a group-level transformer. Floci does not execute
group-level or account-level log transformations, including stored TRANSFORMER_POLICY
configuration. Accepting the flag therefore does not establish transformed-log processing or
full compatibility with an AWS group that has an active transformer.
See Metric-filter contract verification for the scenarios tagged Verified on Live AWS, the recorded fixtures and their evidence boundaries.
Logs Insights
StartQuery accepts log group names and canonical log group ARNs in logGroupIdentifiers.
Floci also accepts the :* suffix and the bare trailing : produced when Grafana removes
the * from DescribeLogGroups.arn. Equivalent identifiers scan the group only once.
The bare-colon tolerance applies only to logGroupIdentifiers, requires a complete Logs ARN,
and does not rewrite values supplied through logGroupName or logGroupNames.
The bare-colon spelling is a client-compatibility tolerance: the
AWS reference
documents the canonical ARN, not that spelling. This tolerance does not change other APIs' ARN handling.
StartQuery / GetQueryResults / StopQuery run a subset of the Logs Insights
query language. As on AWS, StartQuery rejects a queryString longer than 10,000 characters
with InvalidParameterException. Supported commands:
| Command | Notes |
|---|---|
fields a, b, ... |
Projection. Defaults to @timestamp, @message. display is an alias |
filter <field> = 'v' |
Equality. != and == are also accepted; where is an alias. An unquoted value must be a number and compares by value, so n = 2 matches 2 and 2.0. Comparisons can be joined with or (any case) and grouped with parentheses, for example filter (type = 'A' or type = 'B') |
sort <field> [asc\|desc] |
order is an alias |
dedup <field, ...> |
Keeps the first row per unique tuple, applied after sorting |
limit N |
The effective cap is the smallest of this value, the StartQuery limit parameter, and FLOCI_SERVICES_CLOUDWATCHLOGS_MAX_EVENTS_PER_QUERY |
Fields may be @timestamp, @message, @ingestionTime, @ptr, or a dotted path into
a JSON log message (for example level or params.job_id). A @ptr column is always
included in each result row, appended unless fields already names it.
A command or filter operator outside this subset fails the query instead of being dropped:
StartQuery still returns a query id, and GetQueryResults reports status: Failed with no
rows. The reason is not part of the response (the AWS GetQueryResults shape has no such field);
it is written to the server log as Logs Insights query <id> will fail: .... A few inputs still
degrade silently, so it is worth knowing how each case behaves:
| Input | Result |
|---|---|
An unsupported command (stats, parse, ...) |
The query fails. Logged as Unsupported command: stats |
A filter whose operator is not =, != or ==, for example <, <=, >, >=, like /ERROR/ or =~ /ERROR/ |
The query fails. Logged as Unsupported filter expression: ... |
A filter using and, not or \|\|, or with text after the value, as in filter level = 'ERROR' x |
The query fails. AWS evaluates and and not, ignores the trailing text, and rejects an unparenthesized \|\| at StartQuery with MalformedQueryException (use or) |
A blank query, or an empty stage as in a trailing \| |
The query fails. AWS rejects it at StartQuery |
A filter with a backslash escape, a backtick-quoted field name, an expression such as 1+1 in place of the field, or an unquoted value that is not a number, such as level = ERROR or n = 1+1 |
The query fails. AWS interprets them |
| A projected field that does not exist | Rendered as an empty string. No warning |
A sort direction other than asc / desc |
Treated as ascending. No warning |
For matching events by a pattern, FilterLogEvents is the more predictable option today: it
applies the filter pattern syntax (?ERROR ?WARN, { $.level = "ERROR" }, and so on) as AWS does.
Reading events past the limit
FilterLogEvents and GetLogEvents both page, and they signal the end of the results differently
because the AWS APIs do.
FilterLogEvents pages forward only. Its nextToken is an f/<index> offset into the matched set,
so the offset counts matches, not stored events: a request narrowed by --filter-pattern,
--start-time or --log-stream-names pages through only what it matched. A missing token starts
from the oldest match, and a response with no nextToken means pagination is finished, so the
final page omits it. An unrecognized, non-numeric or negative token returns
InvalidParameterException (400). startFromHead is not supported, so results always run oldest
first.
GetLogEvents pages in both directions with f/<index> and b/<index>, and always returns
nextForwardToken and nextBackwardToken. It signals the end by returning the same token it was
given rather than by omitting it, which is what its SDK paginators expect.
Configuration
| Variable | Default | Description |
|---|---|---|
FLOCI_SERVICES_CLOUDWATCHLOGS_ENABLED |
true |
Enable or disable the CloudWatch Logs service |
FLOCI_SERVICES_CLOUDWATCHLOGS_MAX_EVENTS_PER_QUERY |
10000 |
Maximum events returned per FilterLogEvents / GetLogEvents call, and the upper bound for a Logs Insights limit |
FLOCI_SERVICES_CLOUDWATCHLOGS_QUERY_COMPLETION_DELAY_MS |
0 |
Artificial Logs Insights query delay. With 0 a query completes immediately. A positive value emulates the real asynchronous lifecycle (Running → Complete after the delay), which also makes StopQuery on a still-running query return success=true |
Storage
Log groups, streams, filters and resource policies follow the configured storage mode as every
other service does. The event store is the one CloudWatch Logs store under steady append load, so
under persistent mode it is journaled instead of rewritten on every PutLogEvents call: a
batch is appended to cwlogs-events.wal, and cwlogs-events.json is rewritten from memory on
the FLOCI_STORAGE_WAL_COMPACTION_INTERVAL_MS cadence and at shutdown. The store keeps at most
20,000 events per account (FLOCI_SERVICES_CLOUDWATCHLOGS_MAX_STORED_EVENTS), which bounds both
the memory footprint and the size of each snapshot. hybrid remains the alternative when a
bounded delay for every CloudWatch Logs store is acceptable. See
Storage Modes.
Examples
export AWS_ENDPOINT_URL=http://localhost:4566
# Create a log group and stream
aws logs create-log-group --log-group-name /app/backend --endpoint-url $AWS_ENDPOINT_URL
aws logs create-log-stream \
--log-group-name /app/backend \
--log-stream-name 2025/01/app-1 \
--endpoint-url $AWS_ENDPOINT_URL
# Write log events
TIMESTAMP=$(date +%s%3N) # milliseconds
aws logs put-log-events \
--log-group-name /app/backend \
--log-stream-name 2025/01/app-1 \
--log-events "[{\"timestamp\":$TIMESTAMP,\"message\":\"Service started\"}]" \
--endpoint-url $AWS_ENDPOINT_URL
# Read log events
aws logs get-log-events \
--log-group-name /app/backend \
--log-stream-name 2025/01/app-1 \
--endpoint-url $AWS_ENDPOINT_URL
# Search logs
aws logs filter-log-events \
--log-group-name /app/backend \
--filter-pattern "ERROR" \
--endpoint-url $AWS_ENDPOINT_URL
# Run a Logs Insights query
QUERY_ID=$(aws logs start-query \
--log-group-name /app/backend \
--start-time $(($(date +%s) - 3600)) \
--end-time $(date +%s) \
--query-string 'fields @timestamp, @message | sort @timestamp desc | limit 20' \
--query queryId --output text \
--endpoint-url $AWS_ENDPOINT_URL)
aws logs get-query-results \
--query-id "$QUERY_ID" \
--endpoint-url $AWS_ENDPOINT_URL
# Set retention
aws logs put-retention-policy \
--log-group-name /app/backend \
--retention-in-days 30 \
--endpoint-url $AWS_ENDPOINT_URL
CloudWatch Metrics
Protocol: Query (XML), JSON 1.0, and OTLP/HTTP.
The OTLP HTTP metrics endpoint accepts POST /v1/metrics with application/json or
application/x-protobuf, optionally gzip-compressed. Requests are stored separately from classic
CloudWatch metrics, retaining their OTLP resource, scope and metric data. The uncompressed request
limit is 5 MiB and a request may contain at most 1,000 data points. Floci checks each datapoint's
timestamp, the limit of 150 resource, scope and datapoint attributes combined, and the 40,000-byte
metadata limit. Attribute strings are limited to 1,024 UTF-16 code units. Storage follows the
cloudwatchmetrics storage configuration. Metric querying through PromQL is not yet supported, and
the endpoint does not yet implement every CloudWatch OTLP validation rule. Invalid requests return OTLP google.rpc.Status
bodies. When only part of a request is invalid, Floci returns an OTLP partial-success response and
stores only the accepted datapoints. Empty or untyped metrics produce a partial-success message
without increasing the rejected datapoint count.
Stored batches expire 14 days after ingestion and are removed on a later ingestion in the same account
and region. Cleanup runs at most once per minute for each account and region.
With IAM enforcement enabled, requests require AWS credentials and the cloudwatch:PutMetricData
permission. Bearer-token authentication for this endpoint is not implemented.
CloudWatch Query operations accept form-encoded POST requests and root GET requests with
URL query parameters. GET uses the existing handlers, signature validation and IAM policy checks. A monitoring
credential in the Authorization header or presigned URL selects CloudWatch, including
requests with browser Accept headers or unrelated target headers. Unsigned GET requests
select it only for unambiguous supported actions; ordinary S3, SNS and browser requests
retain their existing routing. Only a Query protocol claim can dispatch a CloudWatch GET;
an unclaimed request cannot perform a CloudWatch operation. Header-signed and presigned
requests use the account and region in their credential scope.
Action takes precedence over Operation.
Use Version=2010-08-01 for current GET operations. Omitting the version selects the
legacy 2009-05-15 API, which supports only ListMetrics and GetMetricStatistics.
An invalid version or action returns HTTP 404 InvalidAction; an absent action returns
HTTP 404 UnknownOperationException. IAM policies use the cloudwatch action prefix.
JSON PutMetricData accepts a gzip-compressed body (Content-Encoding: gzip), which the AWS
CLI, boto3 and the other SDKs that call CloudWatch over JSON send by default for any body of
10 KiB or more. With signature validation and IAM enforcement on, the signature is checked over
the compressed bytes as sent and IAM decides the request before the body is decompressed. The
decompressed body is limited to 5 MiB: a larger one returns HTTP 413
RequestEntityTooLargeException, a body that cannot be decompressed returns HTTP 400
InvalidRequestException, and an empty body reads as no input. Other JSON operations do not
decompress their body.
JSON and Query metric publication require finite numeric values in the inclusive range -2^360
through 2^360. They reject incomplete StatisticValues sets and datums combining Value with
StatisticValues before storing any part of the batch. Missing statistics return MissingParameter;
invalid values and non-object statistics return InvalidParameterValue; combining scalar and
statistics returns InvalidParameterCombination. JSON bodies use the corresponding SDK exception
shape names. The console's supported numeric values use the same bounds.
Endpoint: http://localhost:4566/. Query: GET or POST; JSON: POST.
JSON 1.0 requests name their operation in X-Amz-Target with the GraniteServiceVersion20100801.
prefix the AWS SDKs send, or with CloudWatchVersion20130116., the prefix of the CloudWatch
console's API. Both get the same signature validation and IAM checks. The console prefix serves
five operations on the same metrics and alarms, with these request members: PutMetricData
(Namespace, MetricData), ListMetrics
(Namespace, MetricName, Dimensions, NextToken), DescribeAlarms (AlarmNames,
AlarmNamePrefix, MaxRecords, NextToken), GetMetricStatistics (Namespace, MetricName,
Dimensions, StartTime, EndTime, Period, Statistics, Unit) and DeleteAlarms
(AlarmNames). Every result comes back at once, so MaxRecords and NextToken change nothing.
Console metric publication accepts a nonempty array of metric objects with either a finite
numeric Value or a complete numeric StatisticValues object (SampleCount, Sum, Minimum,
Maximum, with positive sample count), with string dimension names and values. Timestamps may
be finite numeric epochs or valid ISO-8601/epoch strings. It rejects malformed batches, conflicting
scalar/statistic-set readings, and unsupported datum fields such as Values, Counts and
StorageResolution before storing any metrics. This supported subset is not complete console
API parity.
It returns HTTP 400 UnsupportedOperation for every other operation, such as the console's
GetMetricData with Defaults and Metrics; for a request that sets any other member, such as
StateValue, ExtendedStatistics or the console's CountOnlyRequest, to a value other than
false or null; and for a DescribeAlarms answer that would list an alarm defined with
Metrics, whose items the console's API shapes differently. Such an alarm makes every listing
that includes it fail, so filter by AlarmNames or AlarmNamePrefix to list the others.
The console prefix is JSON only: a CBOR request naming it returns HTTP 404
UnknownOperationException, and a Smithy RPC v2 request HTTP 404. Only the bare prefix over
application/x-amz-json-1.0 is accepted; the fully qualified
com.amazonaws.cloudwatch.v2013_01_16.CloudWatchVersion20130116. form over application/json
returns HTTP 404.
Supported Actions
| Action | Description |
|---|---|
PutMetricData |
Publish custom metrics |
ListMetrics |
List available metrics |
GetMetricStatistics |
Get metric statistics (Average, Sum, etc.) |
GetMetricData |
Query metrics with math expressions |
PutMetricAlarm |
Create a metric alarm |
PutCompositeAlarm |
Create or update a composite alarm rule |
DescribeAlarms |
List alarms |
DeleteAlarms |
Delete alarms |
DisableAlarmActions |
Disable actions for named metric and composite alarms |
EnableAlarmActions |
Re-enable actions for named metric and composite alarms |
SetAlarmState |
Manually set alarm state |
DescribeAlarmHistory |
List alarm state transitions and configuration changes (see Alarm history) |
PutMetricStream |
Create or update a metric stream definition |
GetMetricStream |
Read a metric stream definition |
ListMetricStreams |
List metric streams |
DeleteMetricStream |
Delete a metric stream |
StartMetricStreams |
Move metric streams to running |
StopMetricStreams |
Move metric streams to stopped |
PutDashboard |
Create a dashboard, or replace its body when the name is taken (tags apply on create only) |
GetDashboard |
Read a dashboard body and ARN |
ListDashboards |
List dashboards, optionally by name prefix |
DeleteDashboards |
Delete dashboards by name |
TagResource |
Tag an alarm or dashboard by ARN |
UntagResource |
Remove tags from an alarm or dashboard |
ListTagsForResource |
List the tags of an alarm or dashboard |
Metric streams are stored as definitions with their running or stopped state. Floci never
delivers metrics to the Firehose delivery stream a metric stream names.
SQS publishes its queue metrics under AWS/SQS once a minute; see
SQS CloudWatch Metrics.
Composite alarms support boolean rules over alarm states. Request AlarmTypes containing
CompositeAlarm when describing them; the default describes metric alarms. Composite
action lists are stored but not executed. Action suppression is not implemented and is
rejected with ValidationError.
Metric alarm updates
Updating a metric alarm preserves its current state, state reason, state timestamps and tags.
Tags supplied to PutMetricAlarm apply only when creating an alarm; use TagResource and
UntagResource to change existing tags. SetAlarmState requires StateReason and rejects
missing or unknown state values before changing the alarm.
StateTransitionedTimestamp records when an alarm's StateValue last changed, while
StateUpdatedTimestamp moves on every state update, including one that keeps the value.
Alarms stored before Floci recorded it report their last state update.
SetAlarmState enforces the modeled maximum lengths of 1023 characters for
StateReason and 4000 characters for StateReasonData before changing alarm state.
Length checks count Unicode code points and preserve empty and whitespace values.
Composite alarm evaluation
A composite alarm is evaluated when it is created, when PutCompositeAlarm updates it, and when
one of its children changes state, up through nested composite alarms. PutMetricAlarm on an
existing child, or a SetAlarmState to the state a child already has, is not a change of state,
so a composite alarm set with SetAlarmState keeps that state until a child really changes. An
update that leaves the state unchanged also keeps the state reason, reason data and timestamps.
A composite alarm on a cycle of rules is not evaluated, not even by the update that closes the
cycle, where CloudWatch evaluates that alarm and the ones after it. One above a cycle is still
evaluated when one of its children changes state. A change of state records the StateReason
CloudWatch writes:
<alarm ARN> was created and its alarm rule evaluates to OKwhen the alarm is created,<alarm ARN> was updated and its new alarm rule evaluates to ALARMwhen an update changes it,<child ARN> transitioned to ALARM at Monday 14 September, 2026 06:29:58 UTCwhen a child does.
StateReasonData lists under triggeringAlarms the children whose state agrees with the new one,
the most recently changed first, each with its state and when it took it. After a child's change
it lists only the children that changed state since the composite alarm last did. The list stops
before the 4000 characters StateReasonData can hold, counted in Unicode code points like the
length checks. Floci keeps state times to the second, so the timestamps end in .000.
Every alarm a rule names must exist, or PutCompositeAlarm fails with ValidationError and
Could not save the composite alarm as alarms [<ARN>] in the alarm rule do not exist.
DeleteAlarms deletes nothing when it names more than one composite alarm
(Cannot delete [2] Composite Alarms as only one composite alarm delete is allowed in single request)
or an alarm that a composite alarm's rule names, even when it deletes that composite alarm too
(Cannot delete <name> as there are composite alarm(s) depending on it.), so delete composite
alarms before their children. Names that match no alarm are ignored.
SNS alarm actions
State transitions publish to same-account standard SNS topics in AlarmActions, OKActions, or
InsufficientDataActions, including transitions from SetAlarmState. Unchanged states and
ActionsEnabled=false suppress notifications. DisableAlarmActions and EnableAlarmActions
update this setting through the Query and current JSON APIs, preserving the alarm's state,
actions, tags, and other configuration. They accept up to 100 names, ignore nonexistent
alarms, and validate the whole request before updating any alarm. Enabling actions does not
replay notifications for transitions that occurred while disabled.
Query requests validate all supplied numeric member indexes, including names after a gap.
The metric evaluator checks current stored action settings before dispatch; disabling does
not cancel actions that have already passed that check.
Scaling action retries remain independent.
Failures are logged per target without blocking other targets. Notifications include a
single-metric Trigger; durable retries, FIFO topics, and metric-math payloads are not covered.
Metric-math alarm definitions
PutMetricAlarm stores the Metrics query definitions and DescribeAlarms returns them over
both JSON and Query protocols. Expressions, labels, ReturnData, account IDs, query periods,
and nested metric statistics (including dimensions and units) survive storage reloads.
Metric-math alarm responses omit the single-metric fields, including top-level Period.
Updating an alarm replaces its metric definition, so changing between Metrics and a single
metric does not retain the previous definition.
This is management-plane support: the alarm evaluator currently evaluates only single-metric
alarms, not metric-math expressions. SetAlarmState remains available for manual transitions.
DescribeAlarms filters
DescribeAlarms applies every filter a request gives: AlarmNames or AlarmNamePrefix,
AlarmTypes, StateValue and ActionPrefix. StateValue and ActionPrefix narrow metric and
composite alarms alike. The API reference calls ActionPrefix a prefix for any action, so an alarm
matches when one of its AlarmActions, OKActions or InsufficientDataActions starts with it.
ChildrenOfAlarmName lists the metric and composite alarms a composite alarm's rule names, by name
or ARN, with only their name, ARN, StateValue and StateUpdatedTimestamp. ParentsOfAlarmName
lists the composite alarms whose rules name an alarm, with only their name and ARN. Neither lists
the alarm it names. Either one with any other member except MaxRecords and NextToken is refused
with ValidationError, as is a StateValue outside OK, ALARM and INSUFFICIENT_DATA, an
empty or over-long ActionPrefix, and an empty or over-long alarm name in either member.
MaxRecords and NextToken are accepted, but every match comes back in one response.
Alarm history
DescribeAlarmHistory lists two kinds of items, newest first unless ScanBy is
TimestampAscending:
StateUpdatefor every real state transition, whether it comes fromSetAlarmState, the alarm evaluator or a composite alarm's rule. Setting an alarm to the state it already has records nothing.HistoryDatacarries the old and new state with their reasons and reason data.ConfigurationUpdatewhenPutMetricAlarmorPutCompositeAlarmcreates or updates an alarm, whenEnableAlarmActionsorDisableAlarmActionschanges its action setting, and whenDeleteAlarmsdeletes one. An update lists the previous value of each changed field underoriginalUpdatedFields.
History survives the deletion of its alarm and is kept for 30 days. Without AlarmTypes only
metric alarm history is listed; request CompositeAlarm to include composite alarms. Action,
AlarmContributorStateUpdate and AlarmContributorAction are accepted filters, but Floci never
records those items, so they match nothing. MaxRecords defaults to 50, and a NextToken issued
for the other ScanBy direction returns an empty page, as on AWS.
The alarm snapshots in ConfigurationUpdate items use Floci's field names, such as okActions
and statistic, where AWS uses its internal ones, such as okactions and extendedStatistic.
Examples
export AWS_ENDPOINT_URL=http://localhost:4566
# Publish a custom metric
aws cloudwatch put-metric-data \
--namespace MyApp \
--metric-data '[{
"MetricName": "RequestCount",
"Value": 42,
"Unit": "Count",
"Dimensions": [{"Name":"Service","Value":"api"}]
}]' \
--endpoint-url $AWS_ENDPOINT_URL
# List metrics
aws cloudwatch list-metrics \
--namespace MyApp \
--endpoint-url $AWS_ENDPOINT_URL
# Get statistics
aws cloudwatch get-metric-statistics \
--namespace MyApp \
--metric-name RequestCount \
--dimensions Name=Service,Value=api \
--start-time $(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ) \
--end-time $(date -u +%Y-%m-%dT%H:%M:%SZ) \
--period 300 \
--statistics Sum \
--endpoint-url $AWS_ENDPOINT_URL
# Create an alarm
aws cloudwatch put-metric-alarm \
--alarm-name high-error-rate \
--metric-name ErrorCount \
--namespace MyApp \
--statistic Sum \
--period 60 \
--threshold 10 \
--comparison-operator GreaterThanThreshold \
--evaluation-periods 1 \
--endpoint-url $AWS_ENDPOINT_URL