Connect to AWS S3¶

View traces stored in an Amazon S3 bucket directly in the extension.

Back to VS Code Extension

Prerequisites¶

An AWS account with an S3 bucket containing Monocle trace files
AWS Access Key ID and Secret Access Key with s3:ListBucket and s3:GetObject permissions on the bucket
Trace files following the Monocle naming convention: monocle_trace_{name}_{id}_{date}.json

Setup Steps¶

Step 1: Select Provider¶

Click the Add Cloud button in the TRACES toolbar and select AWS S3.

Step 2: Enter Access Key ID¶

Enter your AWS Access Key ID (displayed as plain text).

Step 3: Enter Secret Access Key¶

Enter your AWS Secret Access Key (displayed as a masked password field).

Step 4: Enter Bucket Name¶

Enter the S3 bucket name. Must be 3-63 characters, lowercase letters, numbers, dots, and hyphens only.

Step 5: Enter AWS Region¶

Enter the AWS region where your bucket is located (e.g., us-east-1, eu-west-1, ap-southeast-1).

Step 6: Validation¶

The extension validates your credentials by making a ListObjectsV2 call to the bucket. If validation fails, you'll see a specific error message and can choose:

Retry -- Fix and re-enter the failed field
Back -- Go back to a previous step
Cancel -- Abort the setup

Common errors:

Error	Cause	Fix
`InvalidAccessKeyId`	Wrong access key	Re-enter the access key
`SignatureDoesNotMatch`	Wrong secret key	Re-enter the secret key
`NoSuchBucket`	Bucket doesn't exist	Check the bucket name
`PermanentRedirect`	Wrong region	Enter the correct region
`AccessDenied`	Missing permissions	Add `s3:ListBucket` and `s3:GetObject` to the IAM policy

Step 7: Set Criteria (Time Range)¶

Choose which traces to fetch:

Most recent: 10, 20, or 30 traces
Last 12 hours, 24 hours, 2 days, 7 days, 15 days, or 1 month

Note: Trace ID lookup and trace-specific filters (agentic, with/without error) are not available for S3 -- these are Okahu Cloud-only features.

Step 8: Done¶

Your S3 bucket appears in the TRACES sidebar. Expand it to see trace files. Click any trace to open the visualization.

The extension supports navigating S3 "folders" (common prefixes). Trace files are expected at any depth in the bucket, following the naming pattern monocle_trace_*.

When a time range criteria is set, the extension filters objects to those modified within the range using the StartAfter parameter on ListObjectsV2.