Skip to content

Client

CloudWatchLogsClient is the entry point. Create one per process (or per set of credentials), share it between threads/tasks and close it on shutdown. Service functions hang off the client (see Functions).

Function AWS operation Notes
constructor / create / new — validates the config (CONFIG error); the AWS SDK client is built on the first call (region, credential chain or static keys, profile, optional assume role, endpoint override url)
fromEnv() — config from GROW_AWS_CLOUDWATCH_LOGS_*, the standard AWS variables and the AWS SDK default chain; a missing region → CONFIG
sdkClient config / withSdkClient(sdk) — wraps an existing AWS SDK CloudWatch Logs client; Grow TLS, proxy, hooks, headers and User-Agent do not apply to it, and close() leaves it usable
health() DescribeLogGroups (limit 1) never throws for an unhealthy or unreachable service, only for CANCELLED and CONFIG; probe timeout min(requestTimeout, 5 s), no retries; authentication and permission failures still count as reachable (healthy: true, details.auth)
ping() DescribeLogGroups (limit 1) latency of an authenticated call; raises the mapped error (AUTHENTICATION, PERMISSION_DENIED, …)
serverVersion() — always UNSUPPORTED: AWS has no version endpoint
close() — idempotent; flushes the log clients created by this client, stops open live-tail sessions and releases connections

status is ok, unreachable (network error) or the reason the probe failed. The service functions are listed in Functions; client setup in all five languages is in Client setup.

Create, use and close

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

const client = new CloudWatchLogsClient({ region: "eu-central-1", profile: "ops" });
// or CloudWatchLogsClient.fromEnv(); add url: "http://127.0.0.1:5000" for the Moto emulator
const health = await client.health();  // { healthy, status, details }
const latencyMs = await client.ping(); // number (ms)
await client.close();                  // safe to call twice

// Cancellation and per-call deadline: every I/O method accepts { signal }
const status = await client.health({ signal: AbortSignal.timeout(2_000) });
use grow_aws_cloudwatch_logs::{CloudWatchLogsClient, CloudWatchLogsConfig};

let config = CloudWatchLogsConfig::builder().region("eu-central-1").profile("ops").build()?;
let client = CloudWatchLogsClient::new(config)?; // or CloudWatchLogsClient::from_env()?
let health = client.health().await?;  // HealthStatus
let latency = client.ping().await?;   // Duration
client.close().await;                 // safe to call twice

// Cancellation: drop the future, e.g. with a deadline
let status = tokio::time::timeout(std::time::Duration::from_secs(2), client.health()).await;

Without an async runtime, enable the blocking feature:

let client = grow_aws_cloudwatch_logs::blocking::CloudWatchLogsClient::from_env()?;
let health = client.health()?;
client, err := cloudwatchlogs.NewClient(cloudwatchlogs.Config{
    Region:  "eu-central-1",
    Profile: "ops",
}) // or cloudwatchlogs.NewClientFromEnv()
if err != nil {
    return err
}
defer client.Close() // safe to call twice

health, err := client.Health(ctx) // HealthStatus
latency, err := client.Ping(ctx)  // time.Duration

// Cancellation and deadlines come from ctx
ctx2, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()
health, err = client.Health(ctx2)
from grow_aws_cloudwatch_logs import CancelToken, CloudWatchLogsClient, CloudWatchLogsConfig

config = CloudWatchLogsConfig(region="eu-central-1", profile="ops")  # or CloudWatchLogsClient.from_env()
with CloudWatchLogsClient(config) as client:
    health = client.health()    # HealthStatus
    latency_ms = client.ping()  # float (ms)

    # Cancel from another thread
    token = CancelToken()
    health = client.health(cancel=token)
# close() ran; calling it again is safe

AsyncCloudWatchLogsClient (extra [async]) has the same methods as coroutines (await client.health(), await client.aclose(), async with), and honours task cancellation.

CloudWatchLogsConfig config = CloudWatchLogsConfig.builder().region("eu-central-1").profile("ops").build();
try (CloudWatchLogsClient client = CloudWatchLogsClient.create(config)) { // or CloudWatchLogsClient.fromEnv()
  HealthStatus health = client.health();
  Duration latency = client.ping();

  // Async variants return CompletableFuture; cancel(true) cancels the request
  CompletableFuture<HealthStatus> pending = client.healthAsync();
  pending.orTimeout(2, TimeUnit.SECONDS).join();
} // close() is idempotent

Lifecycle rules

  • The client is safe for concurrent use. Reuse it: it keeps a connection pool.
  • close() flushes queued work (for example log batches) within the configured deadline and is safe to call more than once. Any call on a closed client fails with CANCELLED ("<operation>: client is closed").
  • Each language also offers its idiomatic scope: TypeScript try/finally, Rust close().await (plus best-effort Drop), Go defer client.Close(), Python with/async with, Java try-with-resources.