0
# Business Metrics
1

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

4
## Capabilities
5

6
### BusinessMetricsInterceptor
7

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

10
```kotlin { .api }
11
/**
12
 * Appends business metrics to the User-Agent header for AWS telemetry
13
 */
14
class BusinessMetricsInterceptor : HttpInterceptor {
15
    /**
16
     * Modify the request before transmission to add business metrics
17
     * @param context Protocol request interceptor context
18
     * @return Modified HTTP request with business metrics in User-Agent header
19
     */
20
    override suspend fun modifyBeforeTransmit(
21
        context: ProtocolRequestInterceptorContext<Any, HttpRequest>
22
    ): HttpRequest
23
}
24
```
25

26
**Usage Examples:**
27

28
```kotlin
29
import aws.sdk.kotlin.runtime.http.interceptors.businessmetrics.BusinessMetricsInterceptor
30

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

34
// The interceptor automatically adds business metrics to User-Agent:
35
// User-Agent: aws-sdk-kotlin/1.5.33 ... m/J,d,e  
36
// Where m/J,d,e represents:
37
// - J: S3 Express bucket usage
38
// - d: DynamoDB mapper usage  
39
// - e: Credential code provider type
40
```
41

42
### AwsBusinessMetric
43

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

46
```kotlin { .api }
47
/**
48
 * AWS SDK specific business metrics enumeration
49
 */
50
enum class AwsBusinessMetric(override val identifier: String) : BusinessMetric {
51
    /**
52
     * Indicates usage of S3 Express One Zone buckets
53
     */
54
    S3_EXPRESS_BUCKET("J"),
55
    
56
    /**
57
     * Indicates usage of DynamoDB Enhanced Client (Mapper)
58
     */
59
    DDB_MAPPER("d");
60
    
61
    /**
62
     * Business metrics for credential providers
63
     */
64
    enum class Credentials(override val identifier: String) : BusinessMetric {
65
        CREDENTIALS_CODE("e"),
66
        CREDENTIALS_JVM_SYSTEM_PROPERTIES("f"),
67
        CREDENTIALS_ENV_VARS("g"),
68
        CREDENTIALS_ENV_VARS_STS_WEB_ID_TOKEN("h"),
69
        CREDENTIALS_STS_ASSUME_ROLE("i"),
70
        CREDENTIALS_STS_ASSUME_ROLE_WEB_ID("k"),
71
        CREDENTIALS_PROFILE("n"),
72
        CREDENTIALS_PROFILE_SOURCE_PROFILE("o"),
73
        CREDENTIALS_PROFILE_NAMED_PROVIDER("p"),
74
        CREDENTIALS_PROFILE_STS_WEB_ID_TOKEN("q"),
75
        CREDENTIALS_PROFILE_SSO("r"),
76
        CREDENTIALS_SSO("s"),
77
        CREDENTIALS_PROFILE_SSO_LEGACY("t"),
78
        CREDENTIALS_SSO_LEGACY("u"),
79
        CREDENTIALS_PROFILE_PROCESS("v"),
80
        CREDENTIALS_PROCESS("w"),
81
        CREDENTIALS_HTTP("z"),
82
        CREDENTIALS_IMDS("0")
83
    }
84
}
85
```
86

87
### Extension Functions
88

89
Convenient extension functions for adding business metrics to credentials.
90

91
```kotlin { .api }
92
/**
93
 * Emit a business metric into Credentials.attributes
94
 * @param metric The business metric to emit
95
 * @return New Credentials instance with the metric added
96
 */
97
fun Credentials.withBusinessMetric(metric: BusinessMetric): Credentials
98

99
/**
100
 * Emit multiple business metrics into Credentials.attributes  
101
 * @param metrics The set of business metrics to emit
102
 * @return New Credentials instance with the metrics added
103
 */
104
fun Credentials.withBusinessMetrics(metrics: Set<BusinessMetric>): Credentials
105
```
106

107
### Internal Utility Functions
108

109
Functions used internally for metric formatting and validation.
110

111
```kotlin { .api }
112
/**
113
 * Format business metrics for inclusion in User-Agent header with validation and truncation
114
 * @param metrics Set of business metrics to format
115
 * @param logger Logger for error reporting
116
 * @return Formatted metrics string or empty string if no valid metrics
117
 */
118
internal fun formatMetrics(metrics: MutableSet<BusinessMetric>, logger: Logger): String
119
```
120

121
**Usage Examples:**
122

123
```kotlin
124
import aws.sdk.kotlin.runtime.http.interceptors.businessmetrics.*
125
import aws.smithy.kotlin.runtime.auth.awscredentials.Credentials
126

127
// Add single business metric to credentials
128
val credentials: Credentials = // ... obtain credentials
129
val credentialsWithMetric = credentials.withBusinessMetric(
130
    AwsBusinessMetric.Credentials.CREDENTIALS_PROFILE
131
)
132

133
// Add multiple business metrics
134
val multipleMetrics = setOf(
135
    AwsBusinessMetric.S3_EXPRESS_BUCKET,
136
    AwsBusinessMetric.DDB_MAPPER,
137
    AwsBusinessMetric.Credentials.CREDENTIALS_IMDS
138
)
139

140
val credentialsWithMetrics = credentials.withBusinessMetrics(multipleMetrics)
141

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

146
## Metric Categories
147

148
Business metrics are organized into several categories:
149

150
### Service-Specific Metrics
151

152
Track usage of specific AWS service features:
153

154
- **S3 Express Bucket**: S3 Express One Zone storage class usage
155
- **DynamoDB Mapper**: Enhanced DynamoDB client usage patterns
156
- **Lambda Extensions**: AWS Lambda extension usage
157
- **CloudWatch Insights**: CloudWatch Logs Insights query patterns
158

159
### Credential Provider Metrics
160

161
Track how applications obtain AWS credentials:
162

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

171
### Feature Usage Metrics
172

173
Track SDK feature adoption:
174

175
- **Retry Modes**: Standard, adaptive, or legacy retry behavior
176
- **Checksum Validation**: Request/response checksum usage
177
- **Compression**: Request/response compression usage
178
- **HTTP/2**: HTTP/2 protocol usage
179

180
## Configuration
181

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

184
```kotlin { .api }
185
/**
186
 * Maximum length for business metrics string
187
 */
188
const val BUSINESS_METRICS_MAX_LENGTH: Int = 1024
189
```
190

191
**Environment Variables:**
192

193
- `AWS_SDK_UA_APP_ID`: Application identifier for user agent
194
- `AWS_DISABLE_BUSINESS_METRICS`: Disable business metrics collection
195

196
**System Properties:**
197

198
- `aws.userAgentAppId`: Application identifier (JVM)
199
- `aws.disableBusinessMetrics`: Disable metrics collection (JVM)
200

201
## Privacy and Security
202

203
Business metrics are designed with privacy in mind:
204

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

210
## Metric Format
211

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

214
```
215
User-Agent: aws-sdk-kotlin/1.5.33 ... m/J,d,A,F
216
```
217

218
Where `m/` indicates business metrics followed by:
219
- Single character identifiers separated by commas
220
- Maximum length of 1024 characters total
221
- Alphabetical sorting for consistency
222

223
## Integration with Analytics
224

225
Business metrics enable AWS to:
226

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

232
## Error Handling
233

234
Business metrics collection handles errors gracefully:
235

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