---
title: "AWS Lambda"
description: "在 AWS Lambda 函数中进行广泛的事件记录和结构化日志记录，包括 SQS 消费者和事件驱动的处理程序。"
canonical_url: "https://evlog.zhcndoc.com/integrate/frameworks/aws-lambda"
---
# AWS Lambda

> 在 AWS Lambda 函数中进行广泛的事件记录和结构化日志记录，包括 SQS 消费者和事件驱动的处理程序。

AWS Lambda 没有像 Nuxt 或 Express 那样的 **HTTP 中间件生命周期**，因此 evlog 的行为类似于 [独立 TypeScript](https://evlog.zhcndoc.com/integrate/frameworks/standalone)：调用一次 `initLogger()`，然后为**每次调用**（或每条 SQS 消息）使用 `createLogger()` 创建一个日志记录器，最后在工作完成时调用 `log.emit()`。

<prompt :actions="["copy","cursor","claude"]" description="在我的 AWS Lambda 函数中设置 evlog" icon="i-custom-lambda">

在 AWS Lambda 函数中设置 evlog（例如 SQS 消费者）。

- 安装 evlog：pnpm add evlog
- 创建 evlog.config.ts，其中包含 export default defineEvlog({ service: 'my-fn' })
- 在模块加载（冷启动）时导入配置并调用一次 initLogger(toLoggerConfig(config))
- 在处理程序中，为每次调用或每条消息创建一个新的 createLogger({ messageId, ... })
- 使用 log.set() 累加上下文；完成后调用 log.emit()
- 避免在调用之间重复使用单个模块级日志记录器实例（Lambda 会复用运行时）

文档：[https://www.evlog.dev/integrate/frameworks/aws-lambda](https://www.evlog.dev/integrate/frameworks/aws-lambda)
适配器：[https://www.evlog.dev/integrate/adapters/overview](https://www.evlog.dev/integrate/adapters/overview)

</prompt>

## 为何不使用一个全局的 `createLogger`？

Lambda **执行环境会被复用**：同一个进程可以按顺序处理多次调用。模块级变量会持续存在，因此**一个共享的日志记录器实例**可能会将前一次调用的字段泄漏到下一次调用中。

**请这样做：** 仅在顶层（仅配置）调用一次 `initLogger()`，并在处理程序中（或在遍历 SQS 记录时）对每次工作单元**调用 createLogger()**。

**依赖注入**（将 `log` 传入函数）是可选的，它有助于测试和提高代码清晰度，但重要的是**每次调用使用一个日志记录器**，而不是是否使用 DI。

## 快速开始

### 1. 安装

<code-group>

```bash [pnpm]
pnpm add evlog
```

```bash [bun]
bun add evlog
```

```bash [yarn]
yarn add evlog
```

```bash [npm]
npm install evlog
```

</code-group>

### 2. 创建 evlog.config.ts

```typescript [evlog.config.ts]
import { defineEvlog } from 'evlog'

export default defineEvlog({
  service: 'sqs-consumer',
  environment: process.env.NODE_ENV,
})
```

你的 bundler 会将该文件与处理程序一起打包，因此其中的 drain 和 `process.env` 读取会在冷启动时生效。`npx evlog init` 会为你写入它。

### 3. 初始化一次，每次调用记录日志

```typescript [src/handler.ts]
import type { SQSEvent } from 'aws-lambda'
import { initLogger, createLogger, toLoggerConfig } from 'evlog'
import config from '../evlog.config'

initLogger(toLoggerConfig(config))

export async function handler(event: SQSEvent) {
  for (const record of event.Records) {
    const log = createLogger({
      messageId: record.messageId,
      approximateReceiveCount: record.attributes?.ApproximateReceiveCount,
    })

    try {
      log.set({ queue: { name: record.eventSourceARN } })
      // … 解析 record.body 并处理消息
      log.set({ status: 'ok' })
    } catch (error) {
      log.error(error instanceof Error ? error : new Error(String(error)))
      log.set({ status: 'error' })
      throw error
    } finally {
      log.emit()
    }
  }
}
```

如果将整个批次作为一个逻辑单元处理，请在每次处理程序调用中使用**一个** `createLogger()`，并附带批次元数据，而不是为每条记录创建一个日志记录器。

## 标准输出与 `silent` 模式

许多团队通过 stdout 从 **CloudWatch** 获取 Lambda 日志。如果使用**排水适配器**（OTLP、Datadog、Axiom 等），并希望在不产生重复控制台噪声的情况下使用 JSON 或平台专用格式，请在生产环境中设置 `silent: true`。请参阅[配置](https://evlog.zhcndoc.com/reference/configuration#options)。

```typescript [evlog.config.ts]
import { defineEvlog } from 'evlog'
import { createAxiomDrain } from 'evlog/axiom'

export default defineEvlog({
  service: 'sqs-consumer',
  silent: process.env.NODE_ENV === 'production',
  drain: createAxiomDrain(),
})
```

<callout color="warning" icon="i-lucide-alert-triangle">

如果启用了 `silent` 但没有配置 `drain`，事件会被构建但不会写入任何地方。请参阅[配置](https://evlog.zhcndoc.com/reference/configuration#options)中的 `silent` 选项。

</callout>

## 文件涵盖的内容

`toLoggerConfig` 会保留 `initLogger` 接受的所有选项，例如 service、采样、`minLevel`、`redact`、drain 和插件。文件中的 `enrich`、`keep`、`include`、`exclude` 和 `routes` 属于框架中间件选项，因此不适用于处理程序。

## 错误处理

如果需要结构化字段（`why`、`fix`、`link`），请使用 `createError`。将失败映射到 Lambda 返回值或重新抛出错误，以确保 SQS 重试／DLQ 行为保持正确。evlog 不会替代 AWS 的错误语义。

```typescript [src/handler.ts]
import { createError } from 'evlog'

throw createError({
  message: '无效的有效载荷',
  status: 400,
  why: '缺少必需字段',
  fix: '在消息体中包含 orderId',
})
```

## 相关内容

- [独立 TypeScript](https://evlog.zhcndoc.com/integrate/frameworks/standalone)：相同的 `initLogger` + `createLogger` + `emit()` 模型
- [配置](https://evlog.zhcndoc.com/reference/configuration)：`silent`、`env.region`（`AWS_REGION`）、drains
- [宽事件](https://evlog.zhcndoc.com/learn/wide-events)：为每个工作单元设计一个全面的事件。


## Sitemap

See the full [sitemap](https://evlog.zhcndoc.com/sitemap.md) for all pages.