CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-sentry--serverless

Official Sentry SDK for various serverless solutions including AWS Lambda and Google Cloud Functions

—

Pending
Overview
Eval results
Files

aws-services.mddocs/

AWS Services Integration

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.

Capabilities

AWS Services Integration

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

/**
 * Integration for tracking AWS service requests
 * @param options - Configuration options for the integration
 * @returns Integration instance for AWS services monitoring
 */
function awsServicesIntegration(options?: { optional?: boolean }): Integration;

/**
 * @deprecated Use awsServicesIntegration() instead
 * AWS Service Request Tracking integration class
 */
class AWSServices implements Integration {
  static id: string;
  name: string;
  setupOnce(): void;
  setup(client: Client): void;
}

Usage Examples:

import { AWSLambda, awsServicesIntegration } from "@sentry/serverless";

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

// Manual integration setup
AWSLambda.init({
  dsn: "your-dsn-here",
  integrations: [
    awsServicesIntegration({ optional: true }),
    // other integrations...
  ]
});

// Optional integration (won't fail if AWS SDK is missing)
AWSLambda.init({
  dsn: "your-dsn-here",
  integrations: [
    awsServicesIntegration({ optional: true })
  ]
});

Automatic Instrumentation

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

Supported Services

The integration provides enhanced descriptions for specific AWS services:

  • S3 (Simple Storage Service): Includes bucket names in operation descriptions
  • Lambda: Includes function names in operation descriptions
  • All Other Services: Generic operation tracking with service and operation names

Span Creation

For each AWS service request, the integration creates:

  • Span Name: Formatted as aws.{service}.{operation} {parameters}
  • Span Operation: http.client
  • Span Attributes: Includes Sentry semantic attributes for tracing origin

Examples of Instrumented Operations

// S3 Operations
await s3.getObject({ Bucket: 'my-bucket', Key: 'file.txt' }).promise();
// Creates span: "aws.s3.getObject my-bucket"

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

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

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

// SQS Operations
await sqs.sendMessage({ QueueUrl: queueUrl, MessageBody: message }).promise();
// Creates span: "aws.sqs.sendMessage"

Integration Details

Request Lifecycle Tracking

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

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

Error Handling

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

Performance Monitoring

The integration provides detailed performance insights:

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

Configuration Options

Optional Integration

// Mark as optional to prevent failures if AWS SDK is not available
awsServicesIntegration({ optional: true })

When marked as optional:

  • Integration setup won't fail if the AWS SDK module is not found
  • Useful for environments where AWS SDK might not be available
  • Recommended for libraries that might run in different environments

Manual Integration Control

import { AWSLambda } from "@sentry/serverless";

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

// Include only specific integrations
AWSLambda.init({
  dsn: "your-dsn-here",
  integrations: [
    // Include other integrations but exclude AWS services
    // awsServicesIntegration(), // Commented out to disable
  ]
});

Usage in Lambda Functions

Complete Example

import { AWSLambda } from "@sentry/serverless";
import AWS from "aws-sdk";

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

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

exports.handler = AWSLambda.wrapHandler(async (event, context) => {
  // These operations will be automatically traced
  try {
    // S3 operation - creates span "aws.s3.getObject my-data-bucket"
    const s3Object = await s3.getObject({
      Bucket: 'my-data-bucket',
      Key: event.key
    }).promise();
    
    // Lambda invocation - creates span "aws.lambda.invoke data-processor"
    const result = await lambda.invoke({
      FunctionName: 'data-processor',
      Payload: JSON.stringify({ data: s3Object.Body })
    }).promise();
    
    return {
      statusCode: 200,
      body: JSON.stringify({ success: true, result: result.Payload })
    };
  } catch (error) {
    // Error context includes AWS operation details
    throw error;
  }
});

Distributed Tracing

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

Lambda Function Span (aws.lambda.invoke)
├── S3 GetObject Span (aws.s3.getObject my-bucket)
├── DynamoDB Query Span (aws.dynamodb.query)
└── Lambda Invoke Span (aws.lambda.invoke processor-function)

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

Service-Specific Features

S3 Operations

  • Bucket names are included in span names
  • Object keys are captured as span data
  • Multipart upload operations are tracked
  • S3 Select operations include query information

Lambda Operations

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

DynamoDB Operations

  • Table names are captured
  • Query and scan operations include condition expressions
  • Batch operations track item counts
  • Global secondary index usage is monitored

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.

Install with Tessl CLI

npx tessl i tessl/npm-sentry--serverless

docs

aws-lambda.md

aws-services.md

core-sentry.md

gcp-functions.md

index.md

tile.json