Skip to content

Quickstart

Connect to Amazon CloudWatch Logs, create a log group, write two events and search them, then close the client. The client reads GROW_AWS_CLOUDWATCH_LOGS_* first and then the standard AWS variables and credential chain (see Functions → Service configuration).

export AWS_REGION=eu-central-1
export AWS_PROFILE=dev                # or AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY, SSO, IAM role …
export CLOUDWATCH_LOG_GROUP=my-app/api   # optional default group (emf, logClient, logQueryClient)
# Emulator (Moto) instead of AWS:
# export GROW_AWS_CLOUDWATCH_LOGS_URL=http://127.0.0.1:5000

The IAM principal needs the logs: actions you call (for example logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents, logs:DescribeLogGroups, logs:FilterLogEvents; logs:StartLiveTail, logs:StartQuery / logs:GetQueryResults for live tail and Insights).

import { CloudWatchLogsClient } from "@grow-codes/aws-cloudwatch-logs";

const client = CloudWatchLogsClient.fromEnv();
try {
  await client.ensureLogGroup("my-app/api", { retentionDays: 7, tags: { team: "platform" } });
  const res = await client.putLogEvents("my-app/api", "web-1", [
    { timestamp: Date.now(), message: "service started" },
    { timestamp: Date.now(), message: "ERROR something failed" },
  ]);
  console.log(res.accepted, res.rejected);
  for await (const e of client.filterLogEvents({ group: "my-app/api", pattern: "ERROR" })) {
    console.log(e.timestamp, e.message);
  }
} finally {
  await client.close();
}
use grow_aws_cloudwatch_logs::{
    CloudWatchLogsClient, EnsureLogGroupOptions, FilterLogEventsOptions, LogEvent, PutLogEventsOptions,
};

#[tokio::main]
async fn main() -> Result<(), grow_aws_cloudwatch_logs::Error> {
    let client = CloudWatchLogsClient::from_env()?;
    client
        .ensure_log_group("my-app/api", EnsureLogGroupOptions::default().retention_days(7).tag("team", "platform"))
        .await?;
    let res = client
        .put_log_events(
            "my-app/api",
            "web-1",
            vec![LogEvent::new("service started"), LogEvent::new("ERROR something failed")],
            PutLogEventsOptions::default(),
        )
        .await?;
    println!("{} {}", res.accepted, res.rejected);
    let errors = client
        .filter_log_events(FilterLogEventsOptions {
            group: Some("my-app/api".into()),
            pattern: Some("ERROR".into()),
            ..Default::default()
        })
        .try_collect()
        .await?;
    println!("{errors:?}");
    client.close().await;
    Ok(())
}
package main

import (
    "context"
    "fmt"
    "log"

    cloudwatchlogs "github.com/grow-codes-packages/aws-cloudwatch-logs/go"
)

func main() {
    ctx := context.Background()
    client, err := cloudwatchlogs.NewClientFromEnv()
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    if _, err := client.EnsureLogGroup(ctx, "my-app/api", cloudwatchlogs.EnsureLogGroupOptions{
        RetentionDays: cloudwatchlogs.Days(7), Tags: map[string]string{"team": "platform"},
    }); err != nil {
        log.Fatal(err)
    }
    res, err := client.PutLogEvents(ctx, "my-app/api", "web-1", []cloudwatchlogs.LogEvent{
        {Message: "service started"}, {Message: "ERROR something failed"},
    }, cloudwatchlogs.PutLogEventsOptions{})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(res.Accepted, res.Rejected)
    for e, err := range client.FilterLogEvents(ctx, cloudwatchlogs.FilterLogEventsOptions{Group: "my-app/api", Pattern: "ERROR"}) {
        if err != nil {
            log.Fatal(err)
        }
        fmt.Println(e.Timestamp, e.Message)
    }
}
import grow_aws_cloudwatch_logs as sdk

with sdk.CloudWatchLogsClient.from_env() as client:
    client.ensure_log_group("my-app/api", retention_days=7, tags={"team": "platform"})
    res = client.put_log_events(
        "my-app/api",
        "web-1",
        [sdk.InputLogEvent("service started"), sdk.InputLogEvent("ERROR something failed")],
    )
    print(res.accepted, res.rejected)
    for e in client.filter_log_events(group="my-app/api", pattern="ERROR"):
        print(e.timestamp, e.message)

Async code uses AsyncCloudWatchLogsClient (install grow-aws-cloudwatch-logs[async]):

import asyncio
import grow_aws_cloudwatch_logs as sdk

async def main() -> None:
    async with sdk.AsyncCloudWatchLogsClient.from_env() as client:
        await client.ensure_log_group("my-app/api")
        await client.put_log_events("my-app/api", "web-1", [sdk.InputLogEvent("hello")])
        async for e in client.filter_log_events(group="my-app/api", pattern="hello"):
            print(e.message)

asyncio.run(main())
import codes.grow.packages.cloudwatchlogs.*;
import java.util.List;
import java.util.Map;

try (CloudWatchLogsClient client = CloudWatchLogsClient.fromEnv()) {
    client.ensureLogGroup("my-app/api",
        EnsureLogGroupOptions.builder().retentionDays(7).tags(Map.of("team", "platform")).build());
    PutLogEventsResult res = client.putLogEvents("my-app/api", "web-1",
        List.of(LogEvent.of("service started"), LogEvent.of("ERROR something failed")));
    System.out.println(res.accepted() + " " + res.rejected());
    for (FilteredLogEvent e : client.filterLogEvents(
            FilterLogEventsOptions.builder().group("my-app/api").pattern("ERROR").build())) {
        System.out.println(e.timestamp() + " " + e.message());
    }
}

health() checks reachability with a signed DescribeLogGroups call (it never throws), ping() returns the round-trip time of an authenticated call and serverVersion() raises UNSUPPORTED (AWS has no version endpoint).

Next steps

  • Configuration: timeouts, retries, TLS, proxy, environment variables.
  • Functions: the Amazon CloudWatch Logs API of this SDK.
  • Logging: the batching LogClient, logger facade and framework adapters.
  • Error handling: error codes and retries.