0
# User Agent Management
1

2
Comprehensive user agent metadata collection and formatting system that provides detailed client identification for AWS services, including SDK version, platform information, execution environment, and custom metadata.
3

4
## Capabilities
5

6
### AwsUserAgentMetadata
7

8
The main class for managing user agent metadata that formats information for both legacy User-Agent and modern x-amz-user-agent headers.
9

10
```kotlin { .api }
11
/**
12
 * Metadata used to populate User-Agent and x-amz-user-agent headers for AWS service requests
13
 */
14
data class AwsUserAgentMetadata(
15
    val sdkMetadata: SdkMetadata,
16
    val apiMetadata: ApiMetadata,
17
    val osMetadata: OsMetadata,
18
    val languageMetadata: LanguageMetadata,
19
    val execEnvMetadata: ExecutionEnvMetadata? = null,
20
    val frameworkMetadata: FrameworkMetadata? = null,
21
    val appId: String? = null,
22
    val customMetadata: CustomUserAgentMetadata? = null
23
) {
24
    /**
25
     * New-style user agent header value for x-amz-user-agent
26
     */
27
    val xAmzUserAgent: String
28
    
29
    /**
30
     * Legacy user agent header value for User-Agent
31
     */
32
    val userAgent: String
33
    
34
    companion object {
35
        /**
36
         * Load user agent configuration from environment variables and system properties
37
         * @param apiMeta API metadata for the service being called
38
         * @param appId Optional application identifier
39
         * @return Configured AwsUserAgentMetadata instance
40
         */
41
        fun fromEnvironment(apiMeta: ApiMetadata, appId: String? = null): AwsUserAgentMetadata
42
    }
43
}
44
```
45

46
**Usage Examples:**
47

48
```kotlin
49
import aws.sdk.kotlin.runtime.http.*
50

51
// Create metadata from environment
52
val apiMetadata = ApiMetadata(serviceId = "S3", version = "2023-01-01")
53
val userAgentMetadata = AwsUserAgentMetadata.fromEnvironment(apiMetadata)
54

55
// Access formatted headers
56
val xAmzUserAgent = userAgentMetadata.xAmzUserAgent
57
val userAgent = userAgentMetadata.userAgent
58

59
// Create metadata manually
60
val sdkMetadata = SdkMetadata(name = "aws-sdk-kotlin", version = "1.5.33")
61
val osMetadata = OsMetadata(family = OsFamily.LINUX, version = "5.15.0")
62
val languageMetadata = LanguageMetadata(
63
    version = "1.9.0",
64
    extras = mapOf("coroutines" to "1.7.3")
65
)
66

67
val customUserAgent = AwsUserAgentMetadata(
68
    sdkMetadata = sdkMetadata,
69
    apiMetadata = apiMetadata,
70
    osMetadata = osMetadata,
71
    languageMetadata = languageMetadata,
72
    appId = "my-app-v1.0"
73
)
74
```
75

76
### Metadata Components
77

78
Core metadata types that compose the user agent information:
79

80
```kotlin { .api }
81
/**
82
 * SDK identification metadata
83
 */
84
data class SdkMetadata(val name: String, val version: String)
85

86
/**
87
 * API service identification metadata
88
 */
89
data class ApiMetadata(val serviceId: String, val version: String)
90

91
/**
92
 * Operating system metadata
93
 */
94
data class OsMetadata(val family: OsFamily, val version: String? = null)
95

96
/**
97
 * Programming language metadata
98
 */
99
data class LanguageMetadata(
100
    val version: String = KotlinVersion.CURRENT.toString(),
101
    val extras: Map<String, String> = emptyMap()
102
)
103

104
/**
105
 * Execution environment metadata (e.g., Lambda, EC2, ECS)
106
 */
107
data class ExecutionEnvMetadata(val name: String)
108

109
/**
110
 * Framework identification metadata (e.g., Spring Boot, Quarkus)
111
 */
112
data class FrameworkMetadata(val name: String, val version: String)
113
```
114

115
### Custom User Agent Metadata
116

117
Operation-level custom metadata that can be added to requests:
118

119
```kotlin { .api }
120
/**
121
 * Operation context element for adding custom metadata to User-Agent header
122
 */
123
class CustomUserAgentMetadata(
124
    extras: Map<String, String> = mapOf(),
125
    typedExtras: List<TypedUserAgentMetadata> = listOf()
126
) {
127
    /**
128
     * Add additional key-value pairs of metadata
129
     */
130
    fun add(key: String, value: String)
131
    
132
    /**
133
     * Add typed metadata for classified information
134
     */
135
    fun add(metadata: TypedUserAgentMetadata)
136
    
137
    /**
138
     * Combine with another CustomUserAgentMetadata instance
139
     */
140
    operator fun plus(other: CustomUserAgentMetadata): CustomUserAgentMetadata
141
    
142
    companion object {
143
        val ContextKey: AttributeKey<CustomUserAgentMetadata>
144
        internal fun fromEnvironment(provider: PlatformEnvironProvider): CustomUserAgentMetadata
145
    }
146
}
147

148
/**
149
 * Marker interface for classified metadata types
150
 */
151
sealed interface TypedUserAgentMetadata
152

153
/**
154
 * Feature metadata for user agent
155
 */
156
data class FeatureMetadata(val name: String, val version: String? = null) : TypedUserAgentMetadata
157

158
/**
159
 * Configuration metadata for user agent
160
 */
161
data class ConfigMetadata(val name: String, val value: String) : TypedUserAgentMetadata
162
```
163

164
### Extension Properties
165

166
Convenient access to custom user agent metadata from execution context:
167

168
```kotlin { .api }
169
/**
170
 * Get the CustomUserAgentMetadata instance from execution context
171
 */
172
val ExecutionContext.customUserAgentMetadata: CustomUserAgentMetadata
173
```
174

175
**Usage Examples:**
176

177
```kotlin
178
import aws.sdk.kotlin.runtime.http.operation.*
179
import aws.smithy.kotlin.runtime.operation.ExecutionContext
180

181
// Add custom metadata to a request
182
val customMetadata = CustomUserAgentMetadata()
183
customMetadata.add("feature", "s3-transfer-acceleration")
184
customMetadata.add(FeatureMetadata("encryption", "AES256"))
185
customMetadata.add(ConfigMetadata("retry-mode", "adaptive"))
186

187
// Access from execution context
188
val context: ExecutionContext = // ... obtained from operation
189
val metadata = context.customUserAgentMetadata
190
```
191

192
## Environment Variables and Properties
193

194
The user agent system reads configuration from:
195

196
```kotlin { .api }
197
/**
198
 * Environment variable for application ID
199
 */
200
const val AWS_APP_ID_ENV: String = "AWS_SDK_UA_APP_ID"
201

202
/**
203
 * System property for application ID
204
 */
205
const val AWS_APP_ID_PROP: String = "aws.userAgentAppId"
206
```
207

208
## Platform-Specific Implementations
209

210
The user agent system has platform-specific implementations:
211

212
- **JVM Platform**: Includes JVM version, vendor, and Android detection
213
- **Native Platform**: Provides minimal platform information
214
- **Common Platform**: Shared Kotlin version and basic metadata
215

216
## Header Format
217

218
The system generates two header formats:
219

220
1. **x-amz-user-agent**: Modern structured format with detailed metadata
221
2. **User-Agent**: Legacy format for backward compatibility
222

223
Both headers include comprehensive information about the client, SDK, platform, and optional custom metadata for AWS service telemetry and debugging.