Metadata-Version: 2.4
Name: genkit-plugin-aws
Version: 0.5.0
Summary: Genkit AWS Plugin - AWS Observability Integration (X-Ray, CloudWatch)
Project-URL: Bug Tracker, https://github.com/firebase/genkit/issues
Project-URL: Documentation, https://firebase.google.com/docs/genkit
Project-URL: Homepage, https://github.com/firebase/genkit
Project-URL: Repository, https://github.com/firebase/genkit/tree/main/py
Author: Google
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,amazon,artificial-intelligence,aws,generative-ai,genkit,llm,machine-learning,telemetry,xray
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: botocore>=1.35.0
Requires-Dist: genkit
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0
Requires-Dist: opentelemetry-propagator-aws-xray>=1.0.0
Requires-Dist: opentelemetry-sdk-extension-aws>=2.1.0
Requires-Dist: strenum>=0.4.15; python_version < '3.11'
Description-Content-Type: text/markdown

# Genkit AWS Plugin

AWS observability integration for Genkit, enabling telemetry export to AWS X-Ray
(distributed tracing) and CloudWatch (metrics/logs).

## Installation

```bash
pip install genkit-plugin-aws
```

## Quick Start

```python
from genkit.plugins.aws import add_aws_telemetry

# Enable AWS X-Ray telemetry (uses AWS_REGION env var)
add_aws_telemetry()

# Or with explicit region
add_aws_telemetry(region='us-west-2')
```

## Configuration

### Environment Variables

| Variable | Description |
|----------|-------------|
| `AWS_REGION` | AWS region for X-Ray endpoint (required) |
| `AWS_DEFAULT_REGION` | Fallback region if `AWS_REGION` not set |
| `AWS_ACCESS_KEY_ID` | AWS access key (or use IAM role) |
| `AWS_SECRET_ACCESS_KEY` | AWS secret key (or use IAM role) |

### Options

```python
add_aws_telemetry(
    region='us-west-2',          # AWS region (or use AWS_REGION env var)
    log_input_and_output=False,  # Set True to disable PII redaction
    force_dev_export=True,       # Export even in dev environment
    disable_traces=False,        # Set True to disable tracing
)
```

## IAM Permissions

The following IAM permissions are required:

### For Traces (X-Ray)

Attach the `AWSXrayWriteOnlyPolicy` managed policy, or create a custom policy:

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "xray:PutTraceSegments",
                "xray:PutTelemetryRecords"
            ],
            "Resource": "*"
        }
    ]
}
```

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                           AWS Plugin                                    │
├─────────────────────────────────────────────────────────────────────────┤
│  Plugin Entry Point (__init__.py)                                       │
│  └── add_aws_telemetry() - Enable X-Ray/CloudWatch export               │
├─────────────────────────────────────────────────────────────────────────┤
│  telemetry/tracing.py - Distributed Tracing                             │
│  ├── AWS X-Ray OTLP exporter configuration                              │
│  ├── SigV4 authentication for AWS endpoints                             │
│  ├── AwsXRayIdGenerator for X-Ray-compatible trace IDs                  │
│  └── OpenTelemetry integration                                          │
└─────────────────────────────────────────────────────────────────────────┘

Data Flow:
┌──────────────┐    ┌──────────────┐    ┌──────────────────────┐
│ Genkit App   │───►│ OpenTelemetry│───►│ AWS Observability    │
│ (actions,    │    │ SDK + ADOT   │    │ (X-Ray, CloudWatch)  │
│  flows)      │    └──────────────┘    └──────────────────────┘
└──────────────┘
```

## AWS Documentation

- [AWS X-Ray](https://docs.aws.amazon.com/xray/)
- [CloudWatch OTLP Endpoints](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html)
- [ADOT Python Getting Started](https://aws-otel.github.io/docs/getting-started/python-sdk)

## License

Apache-2.0
