aws / aws/aws-durable-execution-docs

Add guidance on emitting custom metrics (EMF) from durable functions

Open
#147 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
13
Forks
13
Avg merge
3d 2h
Merged PRs (30d)
25

Description

### Problem

When using `aws-embedded-metrics` (or similar custom metric libraries) inside a durable function, metrics emitted in the main handler context are emitted **multiple times due to replay**. Wrapping metric emission in `context.step()` ensures metrics are emitted exactly once.

This is a non-obvious gotcha — the same code works correctly in a standard Lambda but produces inflated metric data in a durable function.

### Current state

The [monitoring docs](https://docs.aws.amazon.com/lambda/latest/dg/durable-monitoring.html) cover CloudWatch metrics published by the service, but there is no guidance on emitting custom metrics (EMF, Powertools, PutMetricData) from within durable function code. The replay-awareness requirement is not documented.

### Suggested improvement

- Add a section to the best practices or monitoring docs: **"Emitting custom metrics from durable functions"**
- Document the replay gotcha: always wrap metric emission in `context.step()` to avoid duplicate data points
- Provide a code example showing the correct pattern, e.g.:

```typescript
// ❌ Wrong — emitted on every replay
metrics.putMetric("OrderProcessed", 1);

// ✅ Correct — emitted exactly once
await context.step("emit-metric", async () => {
metrics.putMetric("OrderProcessed", 1);
});
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.