@kensio/yulin 1.20.17 → 1.21.1

package/docs/services/lambda/README.md

@@ -2748,6 +2748,34 @@ otherwise. A time read at module scope is therefore read too early, exactly as i
 variables. See [simulated time](https://yulinsim.dev/time/) for the whole picture, including where real
 AWS puts the time on the event.
 
+## What an invocation counts in CloudWatch
+
+Every invocation publishes `Invocations` and a `Duration` into `AWS/Lambda`, dimensioned by
+`FunctionName`. One whose handler threw publishes an `Errors` beside them. Real Lambda counts a
+failed invocation under both, so an alarm reading one against the other gets a failure rate.
+
+Nothing has to be turned on for it, and the execution Role needs no permission, which is how real
+Lambda behaves. An alarm on `AWS/Lambda` `Errors` can therefore be driven to a state change by
+invoking a function that fails, rather than by publishing a datapoint by hand. `PutMetricData` still
+refuses the `AWS/Lambda` namespace, exactly as an account does. See the
+[CloudWatch docs](../cloudwatch/README.md) for an alarm reading these.
+
+`Duration` is measured on the simulation's clock. A handler that moves the clock reports the time it
+moved, and one that returns without touching it reports nothing spent.
+
+A stream event source mapping publishes `IteratorAge` as well, in milliseconds, once a batch of
+DynamoDB Streams or Kinesis records has been handled. It is the distance between the newest record
+in the batch and the moment the batch finished, measured on the simulation's clock. A test that lets
+records age before anything reads them gets back the interval it let pass. A batch whose handler
+threw is counted too, because the retry leaves the function further behind rather than caught up. A
+queue mapping publishes none of it, and neither does a direct invocation.
+
+`Throttles` and `ConcurrentExecutions` are absent. Both count what a concurrency limit turned away,
+and this simulation applies none.
+
+A function built outside a `SimAws` instance has no simulated CloudWatch to publish into. It runs and
+counts nothing.
+
 ## CloudFormation functions
 
 Sim CloudFormation can create Lambda functions from `AWS::Lambda::Function`, typically alongside a

package/docs/services/logs/README.md

@@ -730,6 +730,277 @@ await simAws.backgroundTasksComplete();
 A qualifier naming no version and no alias is refused where the filter is put, the way a missing
 function is. `UpdateAlias` moves what the filter reaches, and the filter stays as it is.
 
+## Metric filters
+
+A metric filter turns matching log events into CloudWatch metric datapoints. It is how a log line becomes something an alarm can watch, with no handler publishing a metric of its own.
+
+```typescript sim-logs-metric-filter
+/**
+ * Counting matching log lines into a CloudWatch metric.
+ */
+
+import { GetMetricStatisticsCommand } from "@aws-sdk/client-cloudwatch";
+import {
+  CreateLogGroupCommand,
+  CreateLogStreamCommand,
+  PutLogEventsCommand,
+  PutMetricFilterCommand,
+} from "@aws-sdk/client-cloudwatch-logs";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const logGroupName = "/aws/lambda/orders";
+const logStreamName = "2026/08/30/[$LATEST]0f7c1a";
+const startedAt = new Date("2026-08-30T09:00:00Z");
+
+await simAws.clock().setTo(startedAt);
+await simAws.logs().createLogGroup(new CreateLogGroupCommand({ logGroupName }));
+await simAws
+  .logs()
+  .createLogStream(new CreateLogStreamCommand({ logGroupName, logStreamName }));
+
+await simAws.logs().putMetricFilter(
+  new PutMetricFilterCommand({
+    logGroupName,
+    filterName: "handler-errors",
+    filterPattern: "ERROR",
+    metricTransformations: [
+      {
+        metricNamespace: "Orders",
+        metricName: "HandlerErrors",
+        metricValue: "1",
+        unit: "Count",
+      },
+    ],
+  }),
+);
+
+await simAws.logs().putLogEvents(
+  new PutLogEventsCommand({
+    logGroupName,
+    logStreamName,
+    logEvents: [
+      { timestamp: startedAt.getTime(), message: "INFO starting" },
+      { timestamp: startedAt.getTime(), message: "ERROR order has no items" },
+    ],
+  }),
+);
+
+// Publication happens after the write is answered, as it does in an account.
+await simAws.backgroundTasksComplete();
+
+const statistics = new GetMetricStatisticsCommand({
+  Namespace: "Orders",
+  MetricName: "HandlerErrors",
+  StartTime: startedAt,
+  EndTime: new Date(startedAt.getTime() + 60_000),
+  Period: 60,
+  Statistics: ["Sum"],
+});
+const counted = await simAws.cloudWatch().getMetricStatistics(statistics);
+
+// 1. The ERROR line counted and the INFO line did not.
+console.log(counted.Datapoints?.[0]?.Sum);
+```
+
+Datapoints go in through the same `PutMetricData` an ordinary caller uses, into the CloudWatch of the log group's own Account and Region. A datapoint is stamped from the simulation's clock at the instant the event was written.
+
+A transformation carrying a `defaultValue` publishes that value once for a minute that took log events and matched none of them. That is how real CloudWatch Logs keeps a metric reporting through a quiet stretch. A minute a match landed in publishes the match alone. A transformation with no default value publishes nothing for a minute it matched nothing in, and the metric is then left with no datapoint at all over that stretch.
+
+A transformation carrying dimensions cannot also carry a `defaultValue`, and one carrying both is refused. Real CloudWatch Logs allows one or the other, because a default would have to be reported against every dimension value the filter has ever seen.
+
+`DescribeLogGroups` reports how many filters a group has as `metricFilterCount`. `DescribeMetricFilters` takes an optional `logGroupName`. A request naming none, and giving a `metricNamespace` and `metricName`, finds every filter in the Region writing to that metric.
+
+### Values a filter cannot read out of the event
+
+A `metricValue` or a dimension value naming a field of the matched event (`$.bytes`, `$1`) raises `SimLogsUnsupportedOperationException` at `PutMetricFilter`. Reading one needs the pattern to have been parsed structurally, and the structured pattern syntaxes are absent. A literal value publishes.
+
+A filter whose namespace begins `AWS/` is taken, because CloudWatch Logs takes one. The publication is then refused by `PutMetricData`, which reserves those namespaces exactly as real CloudWatch does. The refusal lands on `simAws.logs().metricPublicationFailures` rather than failing the write that produced it, so a filter writing nowhere is something a test can assert on.
+
+### Declaring a metric filter in a template
+
+`AWS::Logs::MetricFilter` deploys through the same `PutMetricFilter`, so a stack's own alarm reads a metric its own log group produced.
+
+```typescript sim-cfn-logs-metric-filter
+/**
+ * Deploying a metric filter and an alarm over the metric it writes.
+ */
+
+import { DescribeAlarmsCommand } from "@aws-sdk/client-cloudwatch";
+import {
+  CreateLogStreamCommand,
+  PutLogEventsCommand,
+} from "@aws-sdk/client-cloudwatch-logs";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const logGroupName = "/aws/lambda/orders";
+const logStreamName = "2026/08/30/[$LATEST]0f7c1a";
+
+await simAws.clock().setTo(new Date("2026-08-30T09:00:00Z"));
+
+await simAws.cloudFormation().deployTemplate({
+  stackName: "orders",
+  template: {
+    Resources: {
+      OrdersLogs: {
+        Type: "AWS::Logs::LogGroup",
+        Properties: { LogGroupName: logGroupName },
+      },
+      OrdersErrors: {
+        Type: "AWS::Logs::MetricFilter",
+        Properties: {
+          LogGroupName: { Ref: "OrdersLogs" },
+          FilterName: "handler-errors",
+          FilterPattern: "ERROR",
+          MetricTransformations: [
+            {
+              MetricNamespace: "Orders",
+              MetricName: "HandlerErrors",
+              MetricValue: "1",
+              Dimensions: [{ Key: "service", Value: "orders" }],
+            },
+          ],
+        },
+      },
+      OrdersFailing: {
+        Type: "AWS::CloudWatch::Alarm",
+        Properties: {
+          AlarmName: "OrdersFailing",
+          Namespace: "Orders",
+          MetricName: "HandlerErrors",
+          Dimensions: [{ Name: "service", Value: "orders" }],
+          Statistic: "Sum",
+          Period: 60,
+          EvaluationPeriods: 3,
+          DatapointsToAlarm: 1,
+          Threshold: 0,
+          ComparisonOperator: "GreaterThanThreshold",
+          TreatMissingData: "notBreaching",
+        },
+      },
+    },
+  },
+});
+
+await simAws
+  .logs()
+  .createLogStream(new CreateLogStreamCommand({ logGroupName, logStreamName }));
+await simAws.logs().putLogEvents(
+  new PutLogEventsCommand({
+    logGroupName,
+    logStreamName,
+    logEvents: [
+      {
+        timestamp: simAws.clock().now().getTime(),
+        message: "ERROR order has no items",
+      },
+    ],
+  }),
+);
+
+await simAws.backgroundTasksComplete();
+await simAws.clock().advanceBy({ minutes: 2 });
+
+const { MetricAlarms } = await simAws
+  .cloudWatch()
+  .describeAlarms(new DescribeAlarmsCommand({ AlarmNames: ["OrdersFailing"] }));
+
+// ALARM. One log line drove it, with nothing publishing a metric by hand.
+console.log(MetricAlarms?.[0]?.StateValue);
+```
+
+`Ref` returns the filter name, and a filter with no `FilterName` is named after the stack and the logical ID. `Dimensions` is a list of `Key` and `Value` pairs in a template and a map through the SDK, and both reach the same filter. Deleting the stack takes the filter with the log group.
+
+## Embedded Metric Format
+
+A log event that is itself an Embedded Metric Format document publishes the metrics it declares. This is how AWS Lambda Powertools counts anything. Its `Metrics` writes an EMF document to the handler's stdout and calls no CloudWatch API at all, and a CDK `NodejsFunction` bundling Powertools does the same in a deployed account.
+
+```typescript sim-logs-embedded-metric-format
+/**
+ * Reading a Powertools style metric out of what a handler printed.
+ */
+
+import { GetMetricStatisticsCommand } from "@aws-sdk/client-cloudwatch";
+import {
+  CreateLogGroupCommand,
+  CreateLogStreamCommand,
+  PutLogEventsCommand,
+} from "@aws-sdk/client-cloudwatch-logs";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const logGroupName = "/aws/lambda/user";
+const logStreamName = "2026/08/30/[$LATEST]0f7c1a";
+const startedAt = new Date("2026-08-30T09:00:00Z");
+
+await simAws.clock().setTo(startedAt);
+await simAws.logs().createLogGroup(new CreateLogGroupCommand({ logGroupName }));
+await simAws
+  .logs()
+  .createLogStream(new CreateLogStreamCommand({ logGroupName, logStreamName }));
+
+// The document Powertools writes to stdout. The metadata names the namespace,
+// the dimension set and the metric, and the body carries the values.
+const document = JSON.stringify({
+  _aws: {
+    Timestamp: startedAt.getTime(),
+    CloudWatchMetrics: [
+      {
+        Namespace: "ChineseBoost",
+        Dimensions: [["service"]],
+        Metrics: [{ Name: "UserRequestFailed", Unit: "Count" }],
+      },
+    ],
+  },
+  service: "user",
+  UserRequestFailed: 1,
+});
+
+await simAws.logs().putLogEvents(
+  new PutLogEventsCommand({
+    logGroupName,
+    logStreamName,
+    logEvents: [{ timestamp: startedAt.getTime(), message: document }],
+  }),
+);
+
+await simAws.backgroundTasksComplete();
+
+const statistics = new GetMetricStatisticsCommand({
+  Namespace: "ChineseBoost",
+  MetricName: "UserRequestFailed",
+  Dimensions: [{ Name: "service", Value: "user" }],
+  StartTime: startedAt,
+  EndTime: new Date(startedAt.getTime() + 300_000),
+  Period: 300,
+  Statistics: ["Sum"],
+});
+const counted = await simAws.cloudWatch().getMetricStatistics(statistics);
+
+// 1. The metric came out of the log line, with nothing calling PutMetricData.
+console.log(counted.Datapoints?.[0]?.Sum);
+```
+
+A bound Lambda handler needs none of this written by hand. Its output already reaches `/aws/lambda/<name>`. A handler bundling Powertools therefore counts through the same path a deployed one does, and invoking it can drive an alarm over the metric to a state change.
+
+`_aws.CloudWatchMetrics[].Dimensions` is a list of dimension key lists, and each inner list is one whole dimension set. A document declaring two sets publishes each of its metrics once per set, which is what makes them separate identities in CloudWatch. A metric whose value is a list of numbers publishes one datapoint per value.
+
+The timestamp comes from `_aws.Timestamp`, read as milliseconds, and from the instant CloudWatch Logs took the event where the document carries none. A handler running inside a simulated Lambda reads the simulation's clock. A Powertools document therefore stamps itself in simulated time without being told to.
+
+### What is left alone, and what is recorded
+
+A log event is read as a document only where it parses as JSON, comes out as an object, and carries usable `_aws` metadata. Anything else is stored and left alone. A log group is full of lines that were never metrics, and treating a parse failure as an error would make the common case the noisy one.
+
+Three things go on `simAws.logs().metricPublicationFailures` rather than passing quietly. A metric the metadata declares and the document body carries no number under, a metric asking for `StorageResolution: 1`, which simulated CloudWatch has no period short enough for, and a directive that asked for dimensions and got no usable set of them.
+
+A dimension set is taken whole or dropped whole. One naming a key the body lacks, and one carrying anything but strings, are both dropped, because publishing part of a set would put the datapoint under a narrower identity than the document declared. A directive left with no usable set publishes nothing at all. Falling back to no dimensions would land the datapoint on the undimensioned metric, and that is one an alarm may well be watching.
+
+Each entry on the ledger names its `source`, which is `{ kind: "metricFilter", filterName }` or `{ kind: "embeddedMetricFormat" }`. The two are told apart by kind rather than by name, because a metric filter may be called anything.
+
 ## Permissions
 
 Every operation goes through simulated IAM. An operation on a named log group authorizes against
@@ -749,6 +1020,12 @@ the three listing operations an SDK caller reaches, and a deployment goes near n
 CloudFormation execution Role therefore carries the same policy here that a real deploy of the
 template needs.
 
+A delivery source over a CloudFront distribution takes one CloudFront permission on top of those.
+CloudWatch Logs checks the caller for `cloudfront:AllowVendedLogDeliveryForResource` against the
+distribution's ARN as the source is put, and a caller holding every `logs:` action and no CloudFront
+permission is refused. A policy naming another distribution is refused the same way. A delivery
+source over a resource of any other service asks for nothing outside `logs:`.
+
 ```typescript sim-logs-permissions
 /**
  * A simulated IAM policy allowing a Role to write one function's logs.
@@ -853,11 +1130,21 @@ console.log(described.logGroups?.[0]?.logGroupArn);
 ## Limitations
 
 - **Events never expire.** Retention is stored and reported, never acted on.
-- **Metric filters.** Absent, so `metricFilterCount` is always zero.
+- **A metric filter reading a field of the log event.** A `metricValue` or a dimension value
+  beginning `$` is refused where the filter is put. Both need a structured filter pattern, and
+  neither structured syntax is simulated.
+- **How far back a `defaultValue` looks.** A filter remembers the most recent minute it matched
+  something in. A later write into that same minute publishes no default over the top, and a write
+  landing in an earlier minute a match was already seen in does publish one. Events
+  arrive in time order in a simulation, so this shows up only where a test writes into the past.
 - **Subscription filter destinations other than Lambda**, and `Distribution`. `Distribution` is
   accepted and reported, and with no shards to spread across it has no effect.
-- **`AWS::Logs::SubscriptionFilter` and `AWS::Logs::MetricFilter`.** Both are recorded as gaps. The
-  log group and the three delivery resource types are what simulated CloudFormation deploys here.
+- **EMF arriving by any route other than a log event.** The document has to reach a log group to be
+  read, which is how it reaches CloudWatch in an account.
+- **`AWS::Logs::SubscriptionFilter`.** Recorded as a gap. The log group, the metric filter and the
+  three delivery resource types are what simulated CloudFormation deploys here.
+- **`ApplyOnTransformedLogs` and `EmitSystemFieldDimensions` on a metric filter.** Recorded and
+  acted on by nothing. Log transformers are absent, so there is no transformed event to read.
 - **Nothing is actually delivered.** A delivery records that a source was joined to a destination
   and how the records would be written. No access log file ever reaches the bucket.
 - **`GetDeliverySource`, `GetDeliveryDestination` and `GetDelivery`.** Absent as SDK operations. The