aws-samples Amazon Rekognition Diagnostics
When to use
Any Amazon Rekognition investigation where the console alone is insufficient — image/video analysis, face detection and collections, custom labels, content moderation, streaming video analysis, or text detection.
Investigation workflow
Step 1 — Collect and triage
aws rekognition list-collections
aws rekognition list-projects
aws rekognition list-stream-processors
Step 2 — Domain deep dive
aws rekognition describe-collection --collection-id <collection-id>
aws rekognition describe-projects --project-names <project-name>
aws rekognition describe-project-versions --project-arn <project-arn>
aws rekognition get-face-detection --job-id <job-id>
Step 3 — Detailed investigation
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=rekognition.amazonaws.com --max-results 20
aws cloudwatch get-metric-statistics --namespace AWS/Rekognition --metric-name SuccessfulRequestCount --start-time <start> --end-time <end> --period 3600 --statistics Sum
Read references/guardrails.md before concluding on any Rekognition issue.
Tool quick reference
| Tool / API | When to use |
|---|---|
rekognition detect-faces |
Analyze faces in image |
rekognition detect-labels |
Detect objects/scenes |
rekognition detect-moderation-labels |
Content moderation |
rekognition start-face-detection |
Async video face detection |
rekognition list-collections |
List face collections |
rekognition describe-projects |
Custom Labels projects |
rekognition list-stream-processors |
Streaming processors |
| CloudWatch metrics | Monitor API calls, errors |
Gotchas: Amazon Rekognition
- Image size limit is 5MB for S3 and 5MB base64 for direct API. Larger images must be resized.
- Video analysis is asynchronous. Start* APIs return a job ID. Use Get* APIs to retrieve results. Results available via SNS notification.
- Face collections have a default limit of face vectors. IndexFaces adds faces; DeleteFaces removes them. Collections are region-specific.
- Custom Labels requires minimum training images (varies by use case, typically 10+ per label). Training can take 30 minutes to 24 hours.
- Content moderation confidence thresholds should be tuned. Default returns all detections. Set MinConfidence to reduce false positives.
- Streaming video processors require Kinesis Video Streams input and Kinesis Data Streams output.
- API calls are throttled per account per region. Implement retry with exponential backoff.
- DetectText has a 100-word limit per image. For documents, use Amazon Textract instead.
Anti-hallucination rules
- Always cite specific collection IDs, project ARNs, or API responses as evidence.
- Video analysis is async. Never assume results are immediately available.
- Custom Labels requires training. Never assume a model works without training.
- Image size limits are strict. Never assume larger images are accepted.
- Face collections are region-specific. Never assume cross-region access.
- Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
14 runbooks
| Category | IDs | Covers |
|---|---|---|
| A — Image Analysis | A1-A2 | Label detection, text detection |
| B — Face Detection | B1-B2 | Face analysis, face collections |
| C — Video Analysis | C1-C2 | Async video jobs, video face detection |
| D — Custom Labels | D1-D3 | Project creation, training, inference |
| E — Content Moderation | E1-E2 | Image moderation, video moderation |
| F — Streaming | F1 | Stream processor issues |
| G — General | G1 | IAM and throttling |
| Z — Catch-All | Z1 | General troubleshooting |