1. Introduction

• CloudWatchLogger for AWS CloudWatch Logs
• PubSubLogger for Google Cloud Pub/Sub

2. Behavior and Context

Both sinks use official cloud SDK clients and lazy dependency imports in initialize(). They are designed to push structured events directly into managed cloud telemetry pipelines.

3. Purpose

• Managed Backend Integration: Native shipping to AWS/GCP services.
• Operational Consolidation: Centralize logs in cloud observability stack.
• Minimal Adapter Surface: Standard sink API with provider-specific internals.

4. High-Level API & Examples

Example 1: AWS CloudWatch

from jazzmine.logging.sinks.cloud_sinks import CloudWatchLogger

sink = CloudWatchLogger(
    sink_config={
        "type": "cloudwatch",
        "log_group": "/apps/chat",
        "log_stream": "api-1",
        "region": "us-east-1",
    },
    logger_name="chat-api",
    level="INFO",
    use_json=True,
)

sink.initialize()
sink.info("deployment complete", version="2026.04.10")
sink.shutdown()

Example 2: Google Pub/Sub

from jazzmine.logging.sinks.cloud_sinks import PubSubLogger

sink = PubSubLogger(
    sink_config={
        "type": "pubsub",
        "project_id": "my-gcp-project",
        "topic": "app-logs",
    },
    logger_name="chat-api",
    level="INFO",
    use_json=True,
)

sink.initialize()
sink.warning("quota near limit", percent=91)
sink.shutdown()

5. Detailed Class Functionality

CloudWatchLogger

initialize()

• Imports boto3 lazily (required).
• Reads log_group, log_stream, region.
• Creates CloudWatch Logs client.
• Ensures log group and log stream exist (ignores already-exists exceptions).
• Tracks sequence_token for ordered writes.

_send_log(level, msg, **kwargs)

• Formats CloudWatch event with millisecond timestamp and JSON message body.
• Calls put_log_events and stores returned nextSequenceToken.

log and alog

• log calls _send_log.
• alog delegates to sync method because boto3 client is synchronous.

PubSubLogger

initialize()

• Imports google.cloud.pubsub_v1 lazily.
• Reads project_id and topic.
• Creates PublisherClient and computed topic_path.

_format_message(level, msg, **kwargs)

Builds JSON payload and encodes UTF-8 bytes for publish API.

log and alog

• log publishes bytes payload asynchronously via client future.
• alog delegates to log (SDK handles async transport internally).

shutdown()

Stops publisher client when initialized.

6. Error Handling

• LoggerDependencyError if required cloud SDK is missing.
• Publish/send exceptions are swallowed.
• Missing/invalid credentials are surfaced by SDK at runtime but not re-raised here.

7. Remarks

• Cloud authentication is environment-driven (IAM role/service account); configure externally.
• For CloudWatch high-throughput scenarios, batching can reduce API overhead.
• For Pub/Sub, ensure topics exist and IAM grants publish permission.