# cwl-link

> Create a CloudWatch Logs Link

Latest version **2.0.0** (published 2026-09-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install cwl-link
pnpm add cwl-link
yarn add cwl-link
bun add cwl-link
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-09-25 |
| First published | 2022-04-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 0 |
| Unpacked size | 58.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Author | michiharu |
| Maintainers | michiharu |
| Keywords | AWS, CloudWatch Logs |

## Links

- npm: https://www.npmjs.com/package/cwl-link
- Repository: https://github.com/michiharu/cwl-link
- Issues: https://github.com/michiharu/cwl-link/issues
- npm.io page: https://npm.io/package/cwl-link

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 2.0.0 (latest) — 2026-09-25
- 1.1.8 — 2025-03-19
- 1.1.7 — 2025-03-05
- 1.1.6 — 2025-03-05
- 1.1.5 — 2024-03-20
- 1.1.4 — 2023-09-22
- 1.1.3 — 2023-09-21
- 1.1.2 — 2023-09-21
- 1.1.1 — 2023-09-21
- 1.1.0 — 2023-09-21
- 1.0.8 — 2022-04-16
- 1.0.7 — 2022-04-16
- 1.0.6 — 2022-04-15
- 1.0.5 — 2022-04-12
- 1.0.4 — 2022-04-12
- … 4 more at https://npm.io/package/cwl-link/versions

## README

# cwl-link(CloudWatch Logs Link)

`cwl-link` creates a link for CloudWatch Logs.

## Installation

`cwl-link` is available as an npm package.

```bash
// with npm
npm install cwl-link

// with yarn
yarn add cwl-link
```

### TypeScript

`cwl-link` ships its own type definitions and does not require `@types/aws-lambda`. The `Context`, `CloudWatchLogsEvent` and `CloudWatchLogsDecodedData` types from `@types/aws-lambda` are accepted as they are.

## Usage

### How to import

```typescript
// ES5 example
const cwllink = require('cwl-link');
// ES6+ example
import * as cwllink from 'cwl-link';
```

```typescript
exports.handler = function(event, context) {
  // This is a link for a Log Event page filtered by request id.
  const link = cwllink.fromLambdaContext(context);
}
```

The region is read from `AWS_REGION`, which the Lambda runtime sets, or you can pass it as the second argument (`cwllink.fromLambdaContext(context, 'us-east-1')`). The same applies to `fromCloudWatchLogsData` and `fromLambdaEventTriggeredBySubscriptionFilters`. If neither is available, the function throws.

### AWS Lambda triggered by Subscription Filters

```typescript
exports.handler = async function(event, context) {
  const link = await cwllink.fromLambdaEventTriggeredBySubscriptionFilters(event);
}
```

Or you can use decoded data.

```typescript
exports.handler = async function(event, context) {
  const decoded = await cwllink.decodeCloudWatchLogsData(event.awslogs.data);

  // you can use decoded data.

  const link = cwllink.fromCloudWatchLogsData(decoded);
}
```

Subscription filters also deliver a `CONTROL_MESSAGE` payload to check that the destination is reachable. It is not log data, so `fromCloudWatchLogsData` and `fromLambdaEventTriggeredBySubscriptionFilters` return the log group link for it. The payload AWS sends has an empty `logGroup`, so in practice that is the log groups list of the region.

### Other Node.js runtime environment

```typescript
const region = '...';
const logGroupName = '...';
const logGroupsLink = cwllink.create(region, ''); // the log groups list of the region
const logGroupLink = cwllink.create(region, logGroupName);

const logEventName = '...';
const logEventLink = cwllink.create(region, logGroupName, logEventName);

const terms = ['...'];
const filteredByTermsLink = cwllink.create(region, logGroupName, logEventName, { terms });

const start = 1_649_602_800_000; // unix time(ms): 2022-04-12 00:00:00
const filteredByStartLink = cwllink.create(region, logGroupName, logEventName, { start });
const start = -3_600_000; // in the last hour(ms):
const filteredByRelativeStartLink = cwllink.create(region, logGroupName, logEventName, { start });

const end = 1_649_689_199_000; // unix time(ms): 2022-04-12 23:59:59
const filteredByEndLink = cwllink.create(region, logGroupName, logEventName, { end });

const filteredByMixLink = cwllink.create(region, logGroupName, logEventName, { terms, start, end });
```

The console host is chosen from the region. `cn-*` regions link to `console.amazonaws.cn`, `us-gov-*` regions link to `console.amazonaws-us-gov.com`, and every other region links to `console.aws.amazon.com`. An empty `logGroup` links to the log groups list of the region instead of a single log group.

These Usages have been tested.

## Caveats

The CloudWatch console URL format is not a documented or stable API.
`cwl-link` builds links by following the format the console uses today,
including its double-encoding with `$` in place of `%`.
If AWS changes this format, generated links may stop working
or open without the filter applied until `cwl-link` is updated.
If you find a broken link, please open an issue.

## Type Aliases

### FilterOptions

Ƭ **FilterOptions**: `Object`

Options for filtering logs.

#### Type declaration

| Name | Type | Description |
| :------ | :------ | :------ |
| `end?` | `number` | You can provide unix timestamp. |
| `start?` | `number` | You can provide the absolute or relative time(ms). - if you provide unix timestamp, it is treated as absolute time. - if you provide negative number, it is treated as relative time. |
| `terms?` | `string`[] | You can filter by string array. |

#### Defined in

[index.ts:5](https://github.com/michiharu/cwl-link/blob/83997cc/src/index.ts#L5)

___

### LambdaContext

Ƭ **LambdaContext**: `Object`

The fields of an AWS Lambda `Context` that this library reads.

#### Type declaration

| Name | Type |
| :------ | :------ |
| `awsRequestId` | `string` |
| `logGroupName` | `string` |
| `logStreamName` | `string` |

___

### CloudWatchLogsEvent

Ƭ **CloudWatchLogsEvent**: `Object`

The event AWS Lambda receives from a CloudWatch Logs subscription filter.

#### Type declaration

| Name | Type |
| :------ | :------ |
| `awslogs` | `{ data: string }` |

___

### CloudWatchLogsDecodedData

Ƭ **CloudWatchLogsDecodedData**: `Object`

The payload of a CloudWatch Logs subscription filter, after base64 decoding and gunzip.

#### Type declaration

| Name | Type |
| :------ | :------ |
| `logEvents` | `CloudWatchLogsLogEvent`[] |
| `logGroup` | `string` |
| `logStream` | `string` |
| `messageType` | `string` |
| `owner` | `string` |
| `subscriptionFilters` | `string`[] |

___

### CloudWatchLogsLogEvent

Ƭ **CloudWatchLogsLogEvent**: `Object`

A log event inside CloudWatchLogsDecodedData.

#### Type declaration

| Name | Type |
| :------ | :------ |
| `extractedFields?` | `object` |
| `id` | `string` |
| `message` | `string` |
| `timestamp` | `number` |

`extractedFields` maps a field name to `string | undefined`.

## Functions

### create

▸ **create**(`region`, `logGroup`, `logEvents?`, `options?`): `string`

Create a link for CloudWatch Logs.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `region` | `string` |  |
| `logGroup` | `string` |  |
| `logEvents?` | `string` | optional parameter |
| `options?` | [`FilterOptions`](modules.md#filteroptions) | optional parameter for filtering logs |

#### Returns

`string`

a link for CloudWatch Logs.

#### Defined in

[index.ts:27](https://github.com/michiharu/cwl-link/blob/83997cc/src/index.ts#L27)

___

### decodeCloudWatchLogsData

▸ **decodeCloudWatchLogsData**(`data`): `Promise`<`CloudWatchLogsDecodedData`\>

Decode CloudWatch Logs data.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `data` | `string` | base64 of zipped data. |

#### Returns

`Promise`<`CloudWatchLogsDecodedData`\>

CloudWatch Logs decoded data.

#### Defined in

[index.ts:93](https://github.com/michiharu/cwl-link/blob/83997cc/src/index.ts#L93)

___

### fromCloudWatchLogsData

▸ **fromCloudWatchLogsData**(`data`, `region?`): `string`

Create a link for CloudWatch Logs from CloudWatchLogsDecodedData.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `data` | `CloudWatchLogsDecodedData` | CloudWatch Logs decoded data. |
| `region?` | `string` | defaults to `AWS_REGION` |

#### Returns

`string`

a link for a Log Event page filtered by request id.

#### Defined in

[index.ts:107](https://github.com/michiharu/cwl-link/blob/83997cc/src/index.ts#L107)

___

### fromLambdaContext

▸ **fromLambdaContext**(`context`, `region?`): `string`

Create a link for CloudWatch Logs from a context of AWS Lambda.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `context` | `LambdaContext` | a context of AWS Lambda. |
| `region?` | `string` | defaults to `AWS_REGION` |

#### Returns

`string`

a link for a Log Event page filtered by request id.

#### Defined in

[index.ts:66](https://github.com/michiharu/cwl-link/blob/83997cc/src/index.ts#L66)

___

### fromLambdaEventTriggeredBySubscriptionFilters

▸ **fromLambdaEventTriggeredBySubscriptionFilters**(`event`, `region?`): `Promise`<`string`\>

Create a link for CloudWatch Logs from a event of AWS Lambda triggered by Subscription Filters.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `event` | `CloudWatchLogsEvent` | a event of AWS Lambda triggered by Subscription Filters. |
| `region?` | `string` | defaults to `AWS_REGION` |

#### Returns

`Promise`<`string`\>

a link for a Log Event page filtered by request id.

#### Defined in

[index.ts:121](https://github.com/michiharu/cwl-link/blob/83997cc/src/index.ts#L121)

___

### gunzipAsync

▸ **gunzipAsync**(`src`): `Promise`<`Buffer`\>

gunzipAsync is a promise wrapper of zlib.gunzip.

#### Parameters

| Name | Type |
| :------ | :------ |
| `src` | `Buffer` |

#### Returns

`Promise`<`Buffer`\>

decompressed

#### Defined in

[index.ts:78](https://github.com/michiharu/cwl-link/blob/83997cc/src/index.ts#L78)

---
_Source: https://npm.io/package/cwl-link · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._