aws-durable-execution-sdk-python-telemetry-exporter 0.0.1__py3-none-any.whl

aws_durable_execution_sdk_python_telemetry_exporter/exporters/aurora_exporter.py

@@ -0,0 +1,152 @@
+# SPDX-FileCopyrightText: 2026-present Amazon.com, Inc. or its affiliates.
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Aurora (RDS Data API) Durable Execution Telemetry exporter."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any, Literal
+
+from aws_durable_execution_sdk_python_telemetry_exporter.exporters._common import (
+    compact_dumps,
+    sql_identifier,
+)
+
+
+class AuroraEngine(StrEnum):
+    """Database engine; selects the upsert dialect."""
+
+    POSTGRESQL = "postgresql"
+    MYSQL = "mysql"
+
+
+# Accepted string inputs, kept in lockstep with the enum values above.
+AuroraEngineInput = Literal["postgresql", "mysql"]
+
+_COLUMNS = (
+    "execution_arn, execution_name, function_name, status, start_time, "
+    "end_time, duration_ms, record_json, emitted_at"
+)
+
+
+def _string_or_null(value: Any) -> dict[str, Any]:
+    return {"stringValue": value} if value else {"isNull": True}
+
+
+class AuroraExporter:
+    """Upserts one row per execution through the RDS Data API.
+
+    Rows are keyed by ``execution_arn``; a later export for the same execution
+    overwrites the row. The full record is stored as JSON in ``record_json``.
+    The cluster must have the Data API enabled.
+    """
+
+    def __init__(
+        self,
+        resource_arn: str,
+        secret_arn: str,
+        database: str,
+        engine: AuroraEngine | AuroraEngineInput,
+        table: str = "durable_execution_telemetry",
+        region: str | None = None,
+        max_record_size_bytes: int | None = None,
+        client: Any = None,
+    ) -> None:
+        self.resource_arn = resource_arn
+        self.secret_arn = secret_arn
+        self.database = database
+        self.table = sql_identifier(table)
+        self.engine = AuroraEngine(engine)
+        self.max_record_size_bytes: int | None = (
+            1_000_000 if max_record_size_bytes is None else max_record_size_bytes
+        )
+        if client is not None:
+            self._client = client
+        else:
+            import boto3  # deferred: boto3 is provided by the Lambda runtime
+
+            self._client = (
+                boto3.client("rds-data", region_name=region)
+                if region
+                else boto3.client("rds-data")
+            )
+
+    def render(self, record: dict[str, Any]) -> dict[str, Any]:
+        return record
+
+    def export(self, record: dict[str, Any]) -> None:
+        sql = (
+            self._postgres_upsert()
+            if self.engine == AuroraEngine.POSTGRESQL
+            else self._mysql_upsert()
+        )
+        duration = record.get("durationMs")
+        self._client.execute_statement(
+            resourceArn=self.resource_arn,
+            secretArn=self.secret_arn,
+            database=self.database,
+            sql=sql,
+            parameters=[
+                {
+                    "name": "execution_arn",
+                    "value": {"stringValue": record["executionArn"]},
+                },
+                {
+                    "name": "execution_name",
+                    "value": _string_or_null(record.get("executionName")),
+                },
+                {
+                    "name": "function_name",
+                    "value": {"stringValue": record["functionName"]},
+                },
+                {"name": "status", "value": {"stringValue": record["status"]}},
+                {"name": "start_time", "value": {"stringValue": record["startTime"]}},
+                {"name": "end_time", "value": _string_or_null(record.get("endTime"))},
+                {
+                    "name": "duration_ms",
+                    "value": {"longValue": duration}
+                    if duration is not None
+                    else {"isNull": True},
+                },
+                {
+                    "name": "record_json",
+                    "value": {"stringValue": compact_dumps(record)},
+                },
+                {"name": "emitted_at", "value": {"stringValue": record["emittedAt"]}},
+            ],
+        )
+
+    def flush(self) -> None:
+        return None
+
+    def _postgres_upsert(self) -> str:
+        return (
+            f"INSERT INTO {self.table}\n"
+            f"      ({_COLUMNS})\n"
+            "    VALUES\n"
+            "      (:execution_arn, :execution_name, :function_name, :status, "
+            ":start_time::timestamptz, :end_time::timestamptz, :duration_ms, "
+            ":record_json::jsonb, :emitted_at::timestamptz)\n"
+            "    ON CONFLICT (execution_arn) DO UPDATE SET\n"
+            "      status = EXCLUDED.status,\n"
+            "      end_time = EXCLUDED.end_time,\n"
+            "      duration_ms = EXCLUDED.duration_ms,\n"
+            "      record_json = EXCLUDED.record_json,\n"
+            "      emitted_at = EXCLUDED.emitted_at"
+        )
+
+    def _mysql_upsert(self) -> str:
+        return (
+            f"INSERT INTO {self.table}\n"
+            f"      ({_COLUMNS})\n"
+            "    VALUES\n"
+            "      (:execution_arn, :execution_name, :function_name, :status, "
+            ":start_time, :end_time, :duration_ms, :record_json, :emitted_at)\n"
+            "    ON DUPLICATE KEY UPDATE\n"
+            "      status = VALUES(status),\n"
+            "      end_time = VALUES(end_time),\n"
+            "      duration_ms = VALUES(duration_ms),\n"
+            "      record_json = VALUES(record_json),\n"
+            "      emitted_at = VALUES(emitted_at)"
+        )

aws_durable_execution_sdk_python_telemetry_exporter/exporters/cloudwatch_logs_exporter.py

@@ -0,0 +1,96 @@
+# SPDX-FileCopyrightText: 2026-present Amazon.com, Inc. or its affiliates.
+#
+# SPDX-License-Identifier: Apache-2.0
+"""CloudWatch Logs (PutLogEvents) Durable Execution Telemetry exporter."""
+
+from __future__ import annotations
+
+import datetime
+import time
+from typing import Any
+
+from aws_durable_execution_sdk_python_telemetry_exporter.exporters._common import (
+    compact_dumps,
+)
+from aws_durable_execution_sdk_python_telemetry_exporter.operations_index import (
+    with_operations_by_name,
+)
+
+
+def _is_already_exists(exc: BaseException) -> bool:
+    if type(exc).__name__ == "ResourceAlreadyExistsException":
+        return True
+    response = getattr(exc, "response", None)
+    if isinstance(response, dict):
+        code = response.get("Error", {}).get("Code")
+        return bool(code == "ResourceAlreadyExistsException")
+    return False
+
+
+class CloudWatchLogsExporter:
+    """Writes ``operationsByName`` records to a chosen log group with PutLogEvents.
+
+    Unlike ``LambdaLogExporter`` this targets any log group. One log stream is
+    created per UTC day, named ``{log_stream_prefix}{YYYY}/{MM}/{DD}``.
+    """
+
+    def __init__(
+        self,
+        log_group_name: str,
+        log_stream_prefix: str = "durable-execution-telemetry/",
+        region: str | None = None,
+        max_record_size_bytes: int | None = None,
+        client: Any = None,
+    ) -> None:
+        self.log_group_name = log_group_name
+        self.log_stream_prefix = log_stream_prefix
+        self.max_record_size_bytes: int | None = (
+            256_000 if max_record_size_bytes is None else max_record_size_bytes
+        )
+        self._created_streams: set[str] = set()
+        if client is not None:
+            self._client = client
+        else:
+            import boto3  # deferred: boto3 is provided by the Lambda runtime
+
+            self._client = (
+                boto3.client("logs", region_name=region)
+                if region
+                else boto3.client("logs")
+            )
+
+    def render(self, record: dict[str, Any]) -> dict[str, Any]:
+        return with_operations_by_name(record)
+
+    def export(self, record: dict[str, Any]) -> None:
+        stream_name = self._build_stream_name()
+        self._ensure_stream(stream_name)
+        self._client.put_log_events(
+            logGroupName=self.log_group_name,
+            logStreamName=stream_name,
+            logEvents=[
+                {
+                    "timestamp": int(time.time() * 1000),
+                    "message": compact_dumps(self.render(record)),
+                }
+            ],
+        )
+
+    def flush(self) -> None:
+        return None
+
+    def _build_stream_name(self) -> str:
+        now = datetime.datetime.now(datetime.UTC)
+        return f"{self.log_stream_prefix}{now:%Y/%m/%d}"
+
+    def _ensure_stream(self, stream_name: str) -> None:
+        if stream_name in self._created_streams:
+            return
+        try:
+            self._client.create_log_stream(
+                logGroupName=self.log_group_name, logStreamName=stream_name
+            )
+        except Exception as exc:
+            if not _is_already_exists(exc):
+                raise
+        self._created_streams.add(stream_name)

aws_durable_execution_sdk_python_telemetry_exporter/exporters/dynamodb_exporter.py

@@ -0,0 +1,75 @@
+# SPDX-FileCopyrightText: 2026-present Amazon.com, Inc. or its affiliates.
+#
+# SPDX-License-Identifier: Apache-2.0
+"""DynamoDB Durable Execution Telemetry exporter."""
+
+from __future__ import annotations
+
+import json
+from decimal import Decimal
+from typing import Any
+
+from aws_durable_execution_sdk_python_telemetry_exporter.exporters._common import (
+    compact_dumps,
+)
+from aws_durable_execution_sdk_python_telemetry_exporter.operations_index import (
+    with_operations_by_name,
+)
+
+
+class DynamoDBExporter:
+    """Writes ``operationsByName`` records to a DynamoDB table with PutItem.
+
+    The partition key holds ``executionArn``. With the default sort key
+    (``sk`` = ``emittedAt``) every export adds a new item, keeping the full
+    history. With ``sort_key=None`` later exports overwrite the item.
+    """
+
+    def __init__(
+        self,
+        table_name: str,
+        partition_key: str = "pk",
+        sort_key: str | None = "sk",
+        region: str | None = None,
+        max_record_size_bytes: int | None = None,
+        client: Any = None,
+    ) -> None:
+        self.table_name = table_name
+        self.partition_key = partition_key
+        # ``None`` and ``""`` both disable the sort key.
+        self.sort_key = sort_key or None
+        self.max_record_size_bytes: int | None = (
+            400_000 if max_record_size_bytes is None else max_record_size_bytes
+        )
+        if client is not None:
+            self._client = client
+        else:
+            import boto3  # deferred: boto3 is provided by the Lambda runtime
+
+            self._client = (
+                boto3.client("dynamodb", region_name=region)
+                if region
+                else boto3.client("dynamodb")
+            )
+        from boto3.dynamodb.types import TypeSerializer  # deferred, same reason
+
+        self._serializer = TypeSerializer()
+
+    def render(self, record: dict[str, Any]) -> dict[str, Any]:
+        return with_operations_by_name(record)
+
+    def export(self, record: dict[str, Any]) -> None:
+        item = self.render(record)
+        item[self.partition_key] = record["executionArn"]
+        if self.sort_key:
+            item[self.sort_key] = record["emittedAt"]
+        self._client.put_item(TableName=self.table_name, Item=self._marshal(item))
+
+    def flush(self) -> None:
+        return None
+
+    def _marshal(self, item: dict[str, Any]) -> dict[str, Any]:
+        # DynamoDB numbers must be ``Decimal``; a JSON round trip converts every
+        # float and leaves the rest of the record untouched.
+        plain = json.loads(compact_dumps(item), parse_float=Decimal)
+        return {key: self._serializer.serialize(value) for key, value in plain.items()}

aws_durable_execution_sdk_python_telemetry_exporter/exporters/eventbridge_exporter.py

@@ -0,0 +1,82 @@
+# SPDX-FileCopyrightText: 2026-present Amazon.com, Inc. or its affiliates.
+#
+# SPDX-License-Identifier: Apache-2.0
+"""EventBridge Durable Execution Telemetry exporter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aws_durable_execution_sdk_python_telemetry_exporter.exporters._common import (
+    compact_dumps,
+    parse_iso_datetime,
+)
+from aws_durable_execution_sdk_python_telemetry_exporter.operations_index import (
+    OperationsFormat,
+    OperationsFormatInput,
+    apply_operations_format,
+)
+
+
+class EventBridgeExporter:
+    """Publishes each record as one EventBridge event with PutEvents.
+
+    ``Source`` is configurable, ``DetailType`` is the record status
+    (``SUCCEEDED``, ``RUNNING``, ``FAILED``), ``Detail`` is the rendered record
+    and ``Time`` is the record's ``emittedAt``.
+    """
+
+    def __init__(
+        self,
+        event_bus_name: str = "default",
+        source: str = "software.amazon.lambda.durable.telemetry",
+        region: str | None = None,
+        operations_format: OperationsFormat | OperationsFormatInput = (
+            OperationsFormat.ARRAY
+        ),
+        max_record_size_bytes: int | None = None,
+        client: Any = None,
+    ) -> None:
+        self.event_bus_name = event_bus_name
+        self.source = source
+        self.operations_format = OperationsFormat(operations_format)
+        self.max_record_size_bytes: int | None = (
+            256_000 if max_record_size_bytes is None else max_record_size_bytes
+        )
+        if client is not None:
+            self._client = client
+        else:
+            import boto3  # deferred: boto3 is provided by the Lambda runtime
+
+            self._client = (
+                boto3.client("events", region_name=region)
+                if region
+                else boto3.client("events")
+            )
+
+    def render(self, record: dict[str, Any]) -> dict[str, Any]:
+        return apply_operations_format(record, self.operations_format)
+
+    def export(self, record: dict[str, Any]) -> None:
+        result = self._client.put_events(
+            Entries=[
+                {
+                    "EventBusName": self.event_bus_name,
+                    "Source": self.source,
+                    "DetailType": record["status"],
+                    "Detail": compact_dumps(self.render(record)),
+                    "Time": parse_iso_datetime(record["emittedAt"]),
+                }
+            ]
+        )
+        if (result or {}).get("FailedEntryCount", 0) > 0:
+            entries = result.get("Entries") or [{}]
+            entry = entries[0]
+            msg = (
+                "EventBridge PutEvents failed: "
+                f"{entry.get('ErrorCode')} — {entry.get('ErrorMessage')}"
+            )
+            raise RuntimeError(msg)
+
+    def flush(self) -> None:
+        return None

aws_durable_execution_sdk_python_telemetry_exporter/exporters/file_exporter.py

@@ -0,0 +1,88 @@
+# SPDX-FileCopyrightText: 2026-present Amazon.com, Inc. or its affiliates.
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Filesystem Durable Execution Telemetry exporter."""
+
+from __future__ import annotations
+
+import json
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Literal
+
+from aws_durable_execution_sdk_python_telemetry_exporter.exporters._common import (
+    compact_dumps,
+    sanitize,
+)
+from aws_durable_execution_sdk_python_telemetry_exporter.operations_index import (
+    OperationsFormat,
+    OperationsFormatInput,
+    apply_operations_format,
+)
+
+
+class FileMode(StrEnum):
+    """File layout."""
+
+    # append every record to one ``{YYYY-MM-DD}.ndjson`` file per day (default)
+    NDJSON = "ndjson"
+    # one pretty-printed ``{executionName}.json`` per execution, overwritten
+    JSON = "json"
+
+
+# Accepted string inputs, kept in lockstep with the enum values above.
+FileModeInput = Literal["ndjson", "json"]
+
+
+class FileExporter:
+    """Writes records under a directory (EFS mount, a mounted share, or ``/tmp``).
+
+    ``ndjson`` appends one compact line per record to ``{directory}/{date}.ndjson``
+    where the date comes from ``emittedAt``. ``json`` writes
+    ``{directory}/{executionName}.json`` and overwrites it on every export.
+    ``max_record_size_bytes`` has no default.
+    """
+
+    def __init__(
+        self,
+        directory: str | Path,
+        mode: FileMode | FileModeInput = FileMode.NDJSON,
+        operations_format: OperationsFormat | OperationsFormatInput = (
+            OperationsFormat.ARRAY
+        ),
+        max_record_size_bytes: int | None = None,
+    ) -> None:
+        self.directory = Path(directory)
+        self.mode = FileMode(mode)
+        self.operations_format = OperationsFormat(operations_format)
+        self.max_record_size_bytes = max_record_size_bytes
+        self._dir_created = False
+
+    def render(self, record: dict[str, Any]) -> dict[str, Any]:
+        return apply_operations_format(record, self.operations_format)
+
+    def export(self, record: dict[str, Any]) -> None:
+        self._ensure_dir()
+        formatted = self.render(record)
+        if self.mode == FileMode.NDJSON:
+            date = str(record["emittedAt"])[:10]  # YYYY-MM-DD
+            path = self.directory / f"{date}.ndjson"
+            with path.open("a", encoding="utf-8") as handle:
+                handle.write(compact_dumps(formatted) + "\n")
+        else:
+            file_name = (
+                sanitize(record.get("executionName") or record["executionArn"])
+                + ".json"
+            )
+            (self.directory / file_name).write_text(
+                json.dumps(formatted, indent=2, ensure_ascii=False), encoding="utf-8"
+            )
+
+    def flush(self) -> None:
+        return None
+
+    def _ensure_dir(self) -> None:
+        if self._dir_created:
+            return
+        self.directory.mkdir(parents=True, exist_ok=True)
+        self._dir_created = True

aws_durable_execution_sdk_python_telemetry_exporter/exporters/firehose_exporter.py

@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: 2026-present Amazon.com, Inc. or its affiliates.
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Kinesis Data Firehose Durable Execution Telemetry exporter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aws_durable_execution_sdk_python_telemetry_exporter.exporters._common import (
+    compact_dumps,
+)
+from aws_durable_execution_sdk_python_telemetry_exporter.operations_index import (
+    OperationsFormat,
+    OperationsFormatInput,
+    apply_operations_format,
+)
+
+
+class FirehoseExporter:
+    """Sends each record to a Firehose delivery stream with PutRecord.
+
+    The data is one JSON line with a trailing newline, so records that Firehose
+    concatenates into a single object stay parseable as NDJSON.
+    """
+
+    def __init__(
+        self,
+        delivery_stream_name: str,
+        region: str | None = None,
+        operations_format: OperationsFormat | OperationsFormatInput = (
+            OperationsFormat.ARRAY
+        ),
+        max_record_size_bytes: int | None = None,
+        client: Any = None,
+    ) -> None:
+        self.delivery_stream_name = delivery_stream_name
+        self.operations_format = OperationsFormat(operations_format)
+        self.max_record_size_bytes: int | None = (
+            1_000_000 if max_record_size_bytes is None else max_record_size_bytes
+        )
+        if client is not None:
+            self._client = client
+        else:
+            import boto3  # deferred: boto3 is provided by the Lambda runtime
+
+            self._client = (
+                boto3.client("firehose", region_name=region)
+                if region
+                else boto3.client("firehose")
+            )
+
+    def render(self, record: dict[str, Any]) -> dict[str, Any]:
+        return apply_operations_format(record, self.operations_format)
+
+    def export(self, record: dict[str, Any]) -> None:
+        data = (compact_dumps(self.render(record)) + "\n").encode("utf-8")
+        self._client.put_record(
+            DeliveryStreamName=self.delivery_stream_name, Record={"Data": data}
+        )
+
+    def flush(self) -> None:
+        return None

aws_durable_execution_sdk_python_telemetry_exporter/exporters/http_exporter.py

@@ -0,0 +1,82 @@
+# SPDX-FileCopyrightText: 2026-present Amazon.com, Inc. or its affiliates.
+#
+# SPDX-License-Identifier: Apache-2.0
+"""HTTP / webhook Durable Execution Telemetry exporter."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any, Literal
+
+from aws_durable_execution_sdk_python_telemetry_exporter.exporters._common import (
+    compact_dumps,
+    http_send,
+)
+from aws_durable_execution_sdk_python_telemetry_exporter.operations_index import (
+    OperationsFormat,
+    OperationsFormatInput,
+    apply_operations_format,
+)
+
+
+class HttpMethod(StrEnum):
+    """Request method. ``PUT`` suits endpoints that upsert by URL path."""
+
+    POST = "POST"
+    PUT = "PUT"
+
+
+# Accepted string inputs, kept in lockstep with the enum values above.
+HttpMethodInput = Literal["POST", "PUT"]
+
+
+class HttpExporter:
+    """Sends each record as a JSON body to any HTTP endpoint.
+
+    The endpoint must answer 2xx; any other status raises. ``timeout_ms``
+    (default 10 seconds) is currently applied to each blocking socket
+    operation, not to the request as a whole: the connect, each write while
+    sending the request (headers and the record body), and each read of the
+    status line and headers, plus of the error body on a non-2xx response. A
+    successful response body is never read. An endpoint that stops reading or
+    goes silent fails at ``timeout_ms``, but one that keeps consuming or
+    sending bytes slowly can hold the request open for longer. A future
+    release may enforce ``timeout_ms`` as a deadline for the whole request, so
+    do not rely on a request being allowed to exceed it. Size the function
+    timeout with this in mind. ``max_record_size_bytes`` has no default because
+    a generic endpoint has no known limit.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        headers: dict[str, str] | None = None,
+        method: HttpMethod | HttpMethodInput = HttpMethod.POST,
+        timeout_ms: int = 10_000,
+        operations_format: OperationsFormat | OperationsFormatInput = (
+            OperationsFormat.ARRAY
+        ),
+        max_record_size_bytes: int | None = None,
+    ) -> None:
+        self.url = url
+        self.method = HttpMethod(method)
+        self.headers = dict(headers or {})
+        self.timeout_ms = timeout_ms
+        self.operations_format = OperationsFormat(operations_format)
+        self.max_record_size_bytes = max_record_size_bytes
+
+    def render(self, record: dict[str, Any]) -> dict[str, Any]:
+        return apply_operations_format(record, self.operations_format)
+
+    def export(self, record: dict[str, Any]) -> None:
+        body = compact_dumps(self.render(record)).encode("utf-8")
+        headers = {"Content-Type": "application/json", **self.headers}
+        status, reason, _ = http_send(
+            self.method.value, self.url, headers, body, timeout=self.timeout_ms / 1000
+        )
+        if not 200 <= status < 300:
+            msg = f"HttpExporter: endpoint returned {status} {reason}"
+            raise RuntimeError(msg)
+
+    def flush(self) -> None:
+        return None

aws_durable_execution_sdk_python_telemetry_exporter/exporters/lambda_log_exporter.py

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: 2026-present Amazon.com, Inc. or its affiliates.
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Lambda log (CloudWatch) Durable Execution Telemetry exporter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aws_durable_execution_sdk_python_telemetry_exporter.exporters._common import (
+    compact_dumps,
+)
+from aws_durable_execution_sdk_python_telemetry_exporter.operations_index import (
+    with_operations_by_name,
+)
+
+
+class LambdaLogExporter:
+    """Writes ``operationsByName`` records to the function's own log group via ``print``.
+
+    Port of the JS ``LambdaLogExporter``: ``console.log(JSON.stringify(
+    withOperationsByName(record)))``. Requires no extra IAM. Emits the name-keyed
+    summary map (``OPERATIONS_BY_NAME``).
+    """
+
+    def __init__(self, max_record_size_bytes: int | None = None) -> None:
+        self.max_record_size_bytes: int | None = (
+            256_000 if max_record_size_bytes is None else max_record_size_bytes
+        )
+
+    def render(self, record: dict[str, Any]) -> dict[str, Any]:
+        return with_operations_by_name(record)
+
+    def export(self, record: dict[str, Any]) -> None:
+        # Raw JSON line to stdout -> the function's CloudWatch log group. The
+        # conformance CloudWatch sink json.loads each line (and unwraps the
+        # Lambda structured-log envelope when present).
+        print(compact_dumps(self.render(record)), flush=True)  # noqa: T201
+
+    def flush(self) -> None:
+        return None