0
# AWS Services Integration
1

2
Automatic tracking and tracing of AWS SDK service requests with detailed operation context, performance monitoring, and error capture for AWS service calls within serverless functions.
3

4
## Capabilities
5

6
### AWS Services Integration
7

8
Automatically instrument AWS SDK calls to provide visibility into service requests made from your serverless functions.
9

10
```typescript { .api }
11
/**
12
 * Integration for tracking AWS service requests
13
 * @param options - Configuration options for the integration
14
 * @returns Integration instance for AWS services monitoring
15
 */
16
function awsServicesIntegration(options?: { optional?: boolean }): Integration;
17

18
/**
19
 * @deprecated Use awsServicesIntegration() instead
20
 * AWS Service Request Tracking integration class
21
 */
22
class AWSServices implements Integration {
23
  static id: string;
24
  name: string;
25
  setupOnce(): void;
26
  setup(client: Client): void;
27
}
28
```
29

30
**Usage Examples:**
31

32
```typescript
33
import { AWSLambda, awsServicesIntegration } from "@sentry/serverless";
34

35
// Automatic inclusion (default behavior)
36
AWSLambda.init({
37
  dsn: "your-dsn-here",
38
  // AWS services integration is included by default
39
});
40

41
// Manual integration setup
42
AWSLambda.init({
43
  dsn: "your-dsn-here",
44
  integrations: [
45
    awsServicesIntegration({ optional: true }),
46
    // other integrations...
47
  ]
48
});
49

50
// Optional integration (won't fail if AWS SDK is missing)
51
AWSLambda.init({
52
  dsn: "your-dsn-here",
53
  integrations: [
54
    awsServicesIntegration({ optional: true })
55
  ]
56
});
57
```
58

59
## Automatic Instrumentation
60

61
The AWS services integration automatically instruments AWS SDK requests to create spans for service calls:
62

63
### Supported Services
64

65
The integration provides enhanced descriptions for specific AWS services:
66

67
- **S3 (Simple Storage Service)**: Includes bucket names in operation descriptions
68
- **Lambda**: Includes function names in operation descriptions
69
- **All Other Services**: Generic operation tracking with service and operation names
70

71
### Span Creation
72

73
For each AWS service request, the integration creates:
74

75
- **Span Name**: Formatted as `aws.{service}.{operation} {parameters}`
76
- **Span Operation**: `http.client`
77
- **Span Attributes**: Includes Sentry semantic attributes for tracing origin
78

79
### Examples of Instrumented Operations
80

81
```typescript
82
// S3 Operations
83
await s3.getObject({ Bucket: 'my-bucket', Key: 'file.txt' }).promise();
84
// Creates span: "aws.s3.getObject my-bucket"
85

86
await s3.putObject({ Bucket: 'uploads', Key: 'new-file.txt', Body: data }).promise();
87
// Creates span: "aws.s3.putObject uploads"
88

89
// Lambda Operations  
90
await lambda.invoke({ FunctionName: 'my-function', Payload: JSON.stringify(payload) }).promise();
91
// Creates span: "aws.lambda.invoke my-function"
92

93
// DynamoDB Operations
94
await dynamodb.query({ TableName: 'Users', KeyConditionExpression: 'id = :id' }).promise();
95
// Creates span: "aws.dynamodb.query"
96

97
// SQS Operations
98
await sqs.sendMessage({ QueueUrl: queueUrl, MessageBody: message }).promise();
99
// Creates span: "aws.sqs.sendMessage"
100
```
101

102
## Integration Details
103

104
### Request Lifecycle Tracking
105

106
The integration hooks into the AWS SDK's request lifecycle:
107

108
1. **Request Build**: Span creation occurs after the request is built
109
2. **Request Execution**: Span is active during the entire request
110
3. **Request Completion**: Span ends when the request completes (success or failure)
111

112
### Error Handling
113

114
- AWS service errors are automatically captured within the span context
115
- Network errors and timeouts are tracked
116
- Service-specific error codes and messages are preserved
117

118
### Performance Monitoring
119

120
The integration provides detailed performance insights:
121

122
- **Request Duration**: Complete time from request initiation to completion
123
- **Service Latency**: Time spent waiting for AWS service responses
124
- **Operation Context**: Which specific AWS operation was performed
125
- **Resource Identification**: Bucket names, function names, and other resource identifiers
126

127
## Configuration Options
128

129
### Optional Integration
130

131
```typescript
132
// Mark as optional to prevent failures if AWS SDK is not available
133
awsServicesIntegration({ optional: true })
134
```
135

136
When marked as optional:
137
- Integration setup won't fail if the AWS SDK module is not found
138
- Useful for environments where AWS SDK might not be available
139
- Recommended for libraries that might run in different environments
140

141
### Manual Integration Control
142

143
```typescript
144
import { AWSLambda } from "@sentry/serverless";
145

146
// Exclude AWS services integration
147
AWSLambda.init({
148
  dsn: "your-dsn-here",
149
  integrations: [] // Empty array excludes default integrations
150
});
151

152
// Include only specific integrations
153
AWSLambda.init({
154
  dsn: "your-dsn-here",
155
  integrations: [
156
    // Include other integrations but exclude AWS services
157
    // awsServicesIntegration(), // Commented out to disable
158
  ]
159
});
160
```
161

162
## Usage in Lambda Functions
163

164
### Complete Example
165

166
```typescript
167
import { AWSLambda } from "@sentry/serverless";
168
import AWS from "aws-sdk";
169

170
// Initialize with AWS services integration (included by default)
171
AWSLambda.init({
172
  dsn: process.env.SENTRY_DSN,
173
  tracesSampleRate: 1.0,
174
});
175

176
const s3 = new AWS.S3();
177
const lambda = new AWS.Lambda();
178

179
exports.handler = AWSLambda.wrapHandler(async (event, context) => {
180
  // These operations will be automatically traced
181
  try {
182
    // S3 operation - creates span "aws.s3.getObject my-data-bucket"
183
    const s3Object = await s3.getObject({
184
      Bucket: 'my-data-bucket',
185
      Key: event.key
186
    }).promise();
187
    
188
    // Lambda invocation - creates span "aws.lambda.invoke data-processor"
189
    const result = await lambda.invoke({
190
      FunctionName: 'data-processor',
191
      Payload: JSON.stringify({ data: s3Object.Body })
192
    }).promise();
193
    
194
    return {
195
      statusCode: 200,
196
      body: JSON.stringify({ success: true, result: result.Payload })
197
    };
198
  } catch (error) {
199
    // Error context includes AWS operation details
200
    throw error;
201
  }
202
});
203
```
204

205
### Distributed Tracing
206

207
AWS service spans are automatically connected to the parent Lambda function span:
208

209
```
210
Lambda Function Span (aws.lambda.invoke)
211
├── S3 GetObject Span (aws.s3.getObject my-bucket)
212
├── DynamoDB Query Span (aws.dynamodb.query)
213
└── Lambda Invoke Span (aws.lambda.invoke processor-function)
214
```
215

216
This provides complete visibility into the service dependency chain within your serverless functions.
217

218
## Service-Specific Features
219

220
### S3 Operations
221

222
- Bucket names are included in span names
223
- Object keys are captured as span data
224
- Multipart upload operations are tracked
225
- S3 Select operations include query information
226

227
### Lambda Operations
228

229
- Function names are included in span names
230
- Invocation types (sync/async) are tracked
231
- Payload sizes are monitored
232
- Function ARNs are captured for cross-account invocations
233

234
### DynamoDB Operations
235

236
- Table names are captured
237
- Query and scan operations include condition expressions
238
- Batch operations track item counts
239
- Global secondary index usage is monitored
240

241
The AWS services integration provides comprehensive observability for AWS service usage within your serverless applications, enabling you to identify performance bottlenecks, track service dependencies, and monitor the health of your cloud infrastructure interactions.