tessl/maven-aws-sdk-kotlin--aws-http-jvm

HTTP core functionality for AWS service clients in the AWS SDK for Kotlin, providing user agent management, retry policies, and HTTP middleware.

—

Pending

Overview

Eval results

Files

Business Metrics

Name: tessl/maven-aws-sdk-kotlin--aws-http-jvm
Author: tessl

AWS telemetry and business metrics collection system that tracks SDK usage patterns, credential providers, and service-specific metrics for analytics, optimization, and operational insights.

Capabilities

BusinessMetricsInterceptor

Interceptor that appends business metrics to the User-Agent header for AWS service telemetry.

/**
 * Appends business metrics to the User-Agent header for AWS telemetry
 */
class BusinessMetricsInterceptor : HttpInterceptor {
    /**
     * Modify the request before transmission to add business metrics
     * @param context Protocol request interceptor context
     * @return Modified HTTP request with business metrics in User-Agent header
     */
    override suspend fun modifyBeforeTransmit(
        context: ProtocolRequestInterceptorContext<Any, HttpRequest>
    ): HttpRequest
}

Usage Examples:

import aws.sdk.kotlin.runtime.http.interceptors.businessmetrics.BusinessMetricsInterceptor

// Create and register the interceptor (typically done by SDK automatically)
val metricsInterceptor = BusinessMetricsInterceptor()

// The interceptor automatically adds business metrics to User-Agent:
// User-Agent: aws-sdk-kotlin/1.5.33 ... m/J,d,e  
// Where m/J,d,e represents:
// - J: S3 Express bucket usage
// - d: DynamoDB mapper usage  
// - e: Credential code provider type

AwsBusinessMetric

Enumeration of AWS SDK-specific business metrics for tracking feature usage patterns.

/**
 * AWS SDK specific business metrics enumeration
 */
enum class AwsBusinessMetric(override val identifier: String) : BusinessMetric {
    /**
     * Indicates usage of S3 Express One Zone buckets
     */
    S3_EXPRESS_BUCKET("J"),
    
    /**
     * Indicates usage of DynamoDB Enhanced Client (Mapper)
     */
    DDB_MAPPER("d");
    
    /**
     * Business metrics for credential providers
     */
    enum class Credentials(override val identifier: String) : BusinessMetric {
        CREDENTIALS_CODE("e"),
        CREDENTIALS_JVM_SYSTEM_PROPERTIES("f"),
        CREDENTIALS_ENV_VARS("g"),
        CREDENTIALS_ENV_VARS_STS_WEB_ID_TOKEN("h"),
        CREDENTIALS_STS_ASSUME_ROLE("i"),
        CREDENTIALS_STS_ASSUME_ROLE_WEB_ID("k"),
        CREDENTIALS_PROFILE("n"),
        CREDENTIALS_PROFILE_SOURCE_PROFILE("o"),
        CREDENTIALS_PROFILE_NAMED_PROVIDER("p"),
        CREDENTIALS_PROFILE_STS_WEB_ID_TOKEN("q"),
        CREDENTIALS_PROFILE_SSO("r"),
        CREDENTIALS_SSO("s"),
        CREDENTIALS_PROFILE_SSO_LEGACY("t"),
        CREDENTIALS_SSO_LEGACY("u"),
        CREDENTIALS_PROFILE_PROCESS("v"),
        CREDENTIALS_PROCESS("w"),
        CREDENTIALS_HTTP("z"),
        CREDENTIALS_IMDS("0")
    }
}

Extension Functions

Convenient extension functions for adding business metrics to credentials.

/**
 * Emit a business metric into Credentials.attributes
 * @param metric The business metric to emit
 * @return New Credentials instance with the metric added
 */
fun Credentials.withBusinessMetric(metric: BusinessMetric): Credentials

/**
 * Emit multiple business metrics into Credentials.attributes  
 * @param metrics The set of business metrics to emit
 * @return New Credentials instance with the metrics added
 */
fun Credentials.withBusinessMetrics(metrics: Set<BusinessMetric>): Credentials

Internal Utility Functions

Functions used internally for metric formatting and validation.

/**
 * Format business metrics for inclusion in User-Agent header with validation and truncation
 * @param metrics Set of business metrics to format
 * @param logger Logger for error reporting
 * @return Formatted metrics string or empty string if no valid metrics
 */
internal fun formatMetrics(metrics: MutableSet<BusinessMetric>, logger: Logger): String

Usage Examples:

import aws.sdk.kotlin.runtime.http.interceptors.businessmetrics.*
import aws.smithy.kotlin.runtime.auth.awscredentials.Credentials

// Add single business metric to credentials
val credentials: Credentials = // ... obtain credentials
val credentialsWithMetric = credentials.withBusinessMetric(
    AwsBusinessMetric.Credentials.CREDENTIALS_PROFILE
)

// Add multiple business metrics
val multipleMetrics = setOf(
    AwsBusinessMetric.S3_EXPRESS_BUCKET,
    AwsBusinessMetric.DDB_MAPPER,
    AwsBusinessMetric.Credentials.CREDENTIALS_IMDS
)

val credentialsWithMetrics = credentials.withBusinessMetrics(multipleMetrics)

// Metrics are automatically included in User-Agent headers:
// User-Agent: aws-sdk-kotlin/1.5.33 ... m/J,d,0

Metric Categories

Business metrics are organized into several categories:

Service-Specific Metrics

Track usage of specific AWS service features:

S3 Express Bucket: S3 Express One Zone storage class usage
DynamoDB Mapper: Enhanced DynamoDB client usage patterns
Lambda Extensions: AWS Lambda extension usage
CloudWatch Insights: CloudWatch Logs Insights query patterns

Credential Provider Metrics

Track how applications obtain AWS credentials:

Default Chain: Standard credential provider chain
Environment Variables: Credentials from environment variables
EC2 Metadata: Instance metadata service credentials
ECS Metadata: ECS task metadata credentials
SSO: AWS Single Sign-On credentials
Profile: Shared credential file usage
STS: Security Token Service operations

Feature Usage Metrics

Track SDK feature adoption:

Retry Modes: Standard, adaptive, or legacy retry behavior
Checksum Validation: Request/response checksum usage
Compression: Request/response compression usage
HTTP/2: HTTP/2 protocol usage

Configuration

Business metrics can be configured through environment variables and system properties:

/**
 * Maximum length for business metrics string
 */
const val BUSINESS_METRICS_MAX_LENGTH: Int = 1024

Environment Variables:

AWS_SDK_UA_APP_ID: Application identifier for user agent
AWS_DISABLE_BUSINESS_METRICS: Disable business metrics collection

System Properties:

aws.userAgentAppId: Application identifier (JVM)
aws.disableBusinessMetrics: Disable metrics collection (JVM)

Privacy and Security

Business metrics are designed with privacy in mind:

No Personal Data: Metrics contain no personally identifiable information
Aggregated Data: Metrics represent usage patterns, not specific requests
Opt-Out Available: Metrics collection can be disabled via configuration
Limited Scope: Only tracks high-level feature usage patterns

Metric Format

Business metrics are encoded in a compact format within User-Agent headers:

User-Agent: aws-sdk-kotlin/1.5.33 ... m/J,d,A,F

Where m/ indicates business metrics followed by:

Single character identifiers separated by commas
Maximum length of 1024 characters total
Alphabetical sorting for consistency

Integration with Analytics

Business metrics enable AWS to:

Optimize Services: Identify popular features for enhancement
Plan Deprecations: Understand feature usage before deprecation
Debug Issues: Correlate issues with specific usage patterns
Improve Documentation: Focus documentation on commonly used features

Error Handling

Business metrics collection handles errors gracefully:

Non-Blocking: Metric collection failures don't affect request processing
Fallback Behavior: Graceful degradation when metrics can't be collected
Size Limits: Automatic truncation if metrics exceed maximum length
Validation: Input validation to prevent malformed metric strings

Install with Tessl CLI

npx tessl i tessl/maven-aws-sdk-kotlin--aws-http-jvm

docs