{"id":39032704,"url":"https://github.com/aws-observability/aws-otel-swift","last_synced_at":"2026-01-17T17:41:46.633Z","repository":{"id":325162393,"uuid":"979692610","full_name":"aws-observability/aws-otel-swift","owner":"aws-observability","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-04T19:12:09.000Z","size":13192,"stargazers_count":3,"open_issues_count":8,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-12-07T05:03:19.703Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-observability.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-07T23:20:55.000Z","updated_at":"2025-11-26T21:28:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aws-observability/aws-otel-swift","commit_stats":null,"previous_names":["aws-observability/aws-otel-swift"],"tags_count":2,"template":false,"template_full_name":"amazon-archives/__template_Apache-2.0","purl":"pkg:github/aws-observability/aws-otel-swift","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-swift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-swift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-swift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-swift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-observability","download_url":"https://codeload.github.com/aws-observability/aws-otel-swift/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-swift/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28513972,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T17:41:46.497Z","updated_at":"2026-01-17T17:41:46.599Z","avatar_url":"https://github.com/aws-observability.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS Distro for OpenTelemetry for Swift\n\nAWS Distro for OpenTelemetry (ADOT) Swift is a redistribution of the [OpenTelemetry Swift](https://github.com/open-telemetry/opentelemetry-swift), configured with in-house instrumentations to use with [AWS CloudWatch Real User Monitoring](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-RUM.html).\n\n## Feature Support\n\n### Available Platforms\n\nAt this time, we only officially support iOS 16+. However, we also have continuation integration in place for latest versions of macOS, tvOS, watchOS, and visionOS.\n\n### Available Instrumentations\n\n| Instrumentation    | Description                                                                                                 | Documentation                                                                   |\n| ------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |\n| **App Launch**     | App launches (cold, warm, and pre-warm)                                                                     | [App Launch README](Sources/AwsOpenTelemetryCore/AppLaunch/README.md)           |\n| **Crashes**        | Crashes with on-device symbolication in Apple format via [KSCrash](https://github.com/kstenerud/KSCrash)    | [Crashes](Sources/AwsOpenTelemetryCore/KSCrash/AwsKSCrashInstrumentation.swift) |\n| **Hangs**          | Application hang detection with live stack traces                                                           | [Hangs](Sources/AwsOpenTelemetryCore/Hang/AwsHangInstrumentation.swift)         |\n| **Network**        | Network requests (currently limited to [URLSession](https://developer.apple.com/documentation/foundation/)) | [Network README](Sources/AwsOpenTelemetryCore/Network/README.md)                |\n| **UIKit**          | View instrumentation for UIKit                                                                              | [UIKitView README](Sources/AwsOpenTelemetryCore/UIKit/README.md)                |\n| **SwiftUI**        | View instrumentation for SwiftUI                                                                            | [SwiftUI README](Sources/AwsOpenTelemetryCore/SwiftUI/README.md)                |\n| **Session Events** | Session lifecycle tracking with start and end events                                                        | [Sessions README](Sources/AwsOpenTelemetryCore/Sessions/README.md)              |\n\n### Available Metadata\n\n| Metadata             | Attribute Name                                     | Description                                                                               |\n| -------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| Session IDs          | `session.id`                                       | UID for the current user session, which by default expires after 30 minutes of inactivity |\n| User IDs (anonymous) | `user.id`                                          | Anonymous UID to enumerate the current user                                               |\n| Screen names         | `screen.name`                                      | The name of the current screen                                                            |\n| Battery usage        | `hw.battery.charge`                                | Battery level as percentage (0.0-1.0)                                                     |\n| CPU usage            | `process.cpu.utilization`                          | CPU utilization ratio (0.0-8.0+)                                                          |\n| Memory usage         | `process.memory.usage`                             | Memory usage in megabytes                                                                 |\n| Device data          | `device.model`, `os.version`, etc.                 | Hardware and OS information                                                               |\n| Network data         | `network.carrier`, `network.connection.type`, etc. | Network connectivity information                                                          |\n\n## Getting Started\n\n### Installation\n\n#### Swift Package Manager (SPM)\n\nAdd the following to your `Package.swift` file:\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/aws-observability/aws-otel-swift.git\", .upToNextMajor(from: \"1.0.0\"))\n]\n```\n\n#### Cocoapods\n\nAt this time, Cocoapods distribution is not supported. Please open an issue to get this work prioritized.\n\n### Zero-Code Initialization\n\nAdd `AwsOpenTelemetryAgent` to target dependencies. This will automatically setup the AWS OTel agent using `AwsOpenTelemetryCore` as a transitive dependency.\n\n```swift\ntargets: [\n    .target(\n        name: \"\u003cyour app target\u003e\",\n        dependencies: [\n            .product(name: \"AwsOpenTelemetryAgent\", package: \"aws-otel-swift\")\n        ]\n    )\n]\n```\n\nThen add `aws_config.json` to your application bundle. See [AwsHackerNewsDemo](Examples/AwsHackerNewsDemo/AwsHackerNewsDemo/aws_config.json) for a complete example.\n\n```json\n{\n  \"aws\": {\n    \"rumAppMonitorId\": \"\u003cyour app monitor id\u003e\",\n    \"region\": \"\u003cyour app monitor region\u003e\"\n  },\n  \"otelResourceAttributes\": {\n    \"service.name\": \"\u003cyour application name\u003e\",\n    \"service.version\": \"1.0.0\"\n  }\n}\n```\n\n### Manual Initialization\n\nAdd `AwsOpenTelemetryCore` to package dependencies. This option is recommended if you would like to directly manage our dependency on OTel.\n\n```swift\ntargets: [\n    .target(\n        name: \"\u003cyour app target\u003e\",\n        dependencies: [\n            .product(name: \"AwsOpenTelemetryCore\", package: \"aws-otel-swift\")\n        ]\n    )\n]\n```\n\nInitialize the ADOT OTel Agent in your AppDelegate\n\n```swift\nimport AwsOpenTelemetryCore\n\nclass AppDelegate: UIResponder, UIApplicationDelegate {\n    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -\u003e Bool {\n        AwsOpenTelemetryRumBuilder.create(\n            config: AwsOpenTelemetryConfig(\n                aws: AwsConfig(\n                    rumAppMonitorId: \"\u003cyour app monitor id\u003e\",\n                    region: \"\u003cyour app monitor region\u003e\"\n                ),\n                otelResourceAttributes: [\n                    \"service.name\": \"\u003cyour application name\u003e\",\n                    \"service.version\": \"1.0.0\"\n                ]\n            )\n        )?.build()\n        return true\n    }\n}\n```\n\n## Configuration\n\n```jsonc\n{\n  \"aws\": {\n    \"region\": \"\u003cyour app monitor region\",\n    \"rumAppMonitorId\": \"\u003cyour app monitor id\u003e\",\n    \"rumAlias\": \"\u003cyour app monitor alias\" // if resource based policy requires alias\n  },\n  \"exportOverride\": {\n    \"logs\": \"http://localhost:3000/v1/logs\", // custom logs otlp endpoint\n    \"traces\": \"http://localhost:3000/v1/traces\" // custom traces otlp endpoint\n  },\n  \"sessionTimeout\": 1800, // in seconds (default 30 minutes)\n  \"sessionSampleRate\": 1.0, // as ratio from 0.0 -\u003e 1.0\n  \"otelResourceAttributes\": {\n    \"service.version\": \"1.0.0\", // optional\n    \"service.name\": \"\u003cyour app name\u003e\" // optional\n  },\n  \"telemetry\": {\n    \"startup\": { \"enabled\": true },\n    \"sessionEvents\": { \"enabled\": true },\n    \"crash\": { \"enabled\": true },\n    \"hang\": { \"enabled\": true },\n    \"network\": { \"enabled\": true },\n    \"view\": { \"enabled\": true }\n  },\n  \"debug\": false // [for dev only] locally print info/warn/debug logs\n}\n```\n\n### Root Configuration\n\n| Field                  | Type                 | Required | Default     | Description                                                                                    |\n| ---------------------- | -------------------- | -------- | ----------- | ---------------------------------------------------------------------------------------------- |\n| aws                    | `AwsConfig`          | Yes      | nil         | AWS service configuration settings (see AwsConfig section)                                     |\n| exportOverride         | `AwsExportOverride`  | No       | nil         | Export endpoint overrides for custom logs and traces endpoints (see AwsExportOverride section) |\n| sessionTimeout         | `Int`                | No       | 30 \\* 60    | Session timeout in seconds. When nil, uses default value                                       |\n| sessionSampleRate      | `Double`             | No       | 1.0         | Session sample rate from 0.0 to 1.0. When nil, uses default value                              |\n| otelResourceAttributes | `Object`             | No       | nil         | Key-value pairs for resource metadata, which are added as resource attributes                  |\n| telemetry              | `AwsTelemetryConfig` | No       | all enabled | Telemetry feature configuration settings (see AwsTelemetryConfig section)                      |\n| debug                  | `Boolean`            | No       | false       | Flag to enable local logging for debugging purposes.                                           |\n\n### AwsConfig\n\n| Field           | Type   | Required | Default | Description                                                                                                                                                                                                                                                                                                                      |\n| --------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| region          | String | Yes      | -       | AWS region where the RUM service is deployed                                                                                                                                                                                                                                                                                     |\n| rumAppMonitorId | String | Yes      | -       | Unique identifier for the RUM App Monitor                                                                                                                                                                                                                                                                                        |\n| rumAlias        | String | No       | nil     | Adds an alias to all requests. It will be compared to the rum:alias service context key in the resource based policy attached to a RUM app monitor. See public docs for using an alias with a [RUM resource based policy](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-RUM-resource-policies.html). |\n\n### AwsExportOverride\n\n| Field  | Type   | Required | Default | Description                                                                                                                               |\n| ------ | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| logs   | String | No       | nil     | Custom endpoint for log exports. When nil, uses AWS CloudWatch RUM OTLP endpoint `https://dataplane.rum.${region}.amazonaws.com/v1/rum`   |\n| traces | String | No       | nil     | Custom endpoint for trace exports. When nil, uses AWS CloudWatch RUM OTLP endpoint `https://dataplane.rum.${region}.amazonaws.com/v1/rum` |\n\n### AwsTelemetryConfig\n\n| Field         | Type   | Required | Default             | Description                                                                                                                                                                                               |\n| ------------- | ------ | -------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| startup       | Object | No       | { \"enabled\": true } | Generate app launch diagnostic as log records.                                                                                                                                                            |\n| sessionEvents | Object | No       | { \"enabled\": true } | Creates `session.start` and `session.end` as log records according to OpenTelemetry Semantic Convention. As an ADOT-Swift extension, `session.end` also includes `duration` and `end_time`.               |\n| crash         | Object | No       | { \"enabled\": true } | Generate crash diagnostic as log records.                                                                                                                                                                 |\n| network       | Object | No       | { \"enabled\": true } | Generate spans of URLSession HTTP requests directly from OTel Swift's implementation of URLSessionInstrumentation. HTTP requests to the logs and spans endpoints are ignored to avoid infinite recursion. |\n| hang          | Object | No       | { \"enabled\": true } | Generate hang diagnostic as log records.                                                                                                                                                                  |\n| view          | Object | No       | { \"enabled\": true } | Create spans from views created with UIKit and SwiftUI.                                                                                                                                                   |\n\n## Export Strategy\n\nThe AWS OpenTelemetry Swift SDK uses OTLP (OpenTelemetry Protocol) over HTTP to export telemetry data to AWS CloudWatch RUM. The SDK supports multiple authentication methods and export configurations.\n\n### Default Export Behavior\n\nBy default, the SDK exports telemetry data with unsigned requests, which is the recommended pattern for monitoring real users. Please refer to AWS docs for allowing [unauthenticated ingestion via RUM resource based policy](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-RUM-resource-policies.html).\n\n| Field                | Type              | Required | Default                             | Description                                                       |\n| -------------------- | ----------------- | -------- | ----------------------------------- | ----------------------------------------------------------------- |\n| maxRetries           | `Int`             | No       | 3                                   | Maximum number of retry attempts                                  |\n| retryableStatusCodes | `Set\u003cInt\u003e`        | No       | [408, 429, 500, 502, 503, 504, 509] | HTTP status codes that trigger retry logic                        |\n| maxBatchSize         | `Int`             | No       | 100                                 | Maximum batch size for exports                                    |\n| maxQueueSize         | `Int`             | No       | 1048                                | Maximum in-memory queue size (separate queues for logs and spans) |\n| batchInterval        | `TimeInterval`    | No       | 5.0                                 | Batch export interval in seconds                                  |\n| exportTimeout        | `TimeInterval`    | No       | 30.0                                | Export timeout in seconds                                         |\n| compression          | `CompressionType` | No       | .gzip                               | Compression type for OTLP exports                                 |\n\nSee the [AwsExportConfig](Sources/AwsOpenTelemetryCore/Configuration/AwsExporterConfig.swift) for detailed configuration options.\n\n### SigV4 Authentication\n\nFor scenarios requiring authenticated requests, the SDK supports AWS Signature Version 4 (SigV4) authentication using the `AwsOpenTelemetryAuth` module:\n\n```swift\nimport AwsOpenTelemetryCore\nimport AwsOpenTelemetryAuth\n\nclass CustomIdentityProvider: CredentialsProviding {\n    func getCredentials() async throws -\u003e Credentials {\n        // Your custom credential logic here\n        return Credentials(...)\n    }\n}\n\n// Create SigV4 exporters (uses default AWS RUM regional endpoints)\nlet customProvider = CustomIdentityProvider()\nlet sigV4SpanExporter = AwsSigV4SpanExporter(\n    region: \"us-east-1\",\n    credentialsProvider: customProvider\n)\nlet sigV4LogExporter = AwsSigV4LogRecordExporter(\n    region: \"us-east-1\",\n    credentialsProvider: customProvider\n)\n\n// Add to agent builder\nAwsOpenTelemetryRumBuilder.create(config: config)?\n    .addSpanExporterCustomizer { _ in sigv4SpanExporter }\n    .addLogRecordExporterCustomizer { _ in sigv4LogExporter }\n    .build()\n```\n\n- [Read more about configuring the SDK with authentication](docs/auth.md)\n- See the [AwsOpenTelemetryAuth README](Sources/AwsOpenTelemetryAuth/README.md) for detailed explanations on AwsOpenTelemetryAuth\n\n## Crash Report Symbolication\n\n| Method          | Support Status   | Description                                                                                                                                                                                                                                                     |\n| --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Server-side** | ❌ Not supported | Please [open an issue](https://github.com/aws-observability/aws-otel-swift/issues) to prioritize this important feature!                                                                                                                                        |\n| **On-device**   | ✅ Supported     | Enable [on-device symbolication via KSCrash](https://github.com/kstenerud/KSCrash?tab=readme-ov-file#enabling-on-device-symbolication) by setting Strip Style to Debugging Symbols, which comes with the tradeoff of approximately ~5% increase in binary size. |\n| **Offline**     | ✅ Supported     | We've provided [a script in `Examples/Symbolication`](Examples/Symbolication/) to help with offline symbolication via `atos`, which also includes swift demangling. Offline symbolication is always possible via XCode or the native `atos` tool .              |\n\n## Custom Events\n\nYou can create custom span and log events using the OpenTelemetry APIs. The SDK provides convenient access to configured tracer and logger instances. All events are populated with [available metadata](#available-metadata) by ADOT Swift.\n\nPlease be mindful about the following restrictions:\n\n1. AWS RUM OTLP endpoint enforces a 30KB limit on attribute size. If an event attribute exceeds the limit, then it is dropped from the payload.\n2. AWS RUM OTLP endpoint requires `spanName` to be set for successful ingestion.\n3. AWS RUM OTLP endpoint requires log to be events, so you must set log `eventName` for successful ingestion.\n\n[Read more about custom events you can manually record](docs/custom_events.md)\n\n### Custom Span Example\n\nUse spans for events with durations and tracing support ([read more](https://opentelemetry.io/docs/concepts/signals/traces/)). **Warning:** `spanName` must be set for successful ingestion.\n\n```swift\n// Example: a database query can be recorded as a span\nimport AwsOpenTelemetryCore\nimport OpenTelemetryApi\n\n// Get the configured tracer\nlet tracer = AwsOpenTelemetryAgent.getTracer()\n\n// Track a database query operation\nlet span = tracer.spanBuilder(spanName: \"database.query\") // `spanName` is REQUIRED\n    .startSpan()\nspan.setAttribute(key: \"db.operation\", value: \"SELECT\")\nspan.setAttribute(key: \"db.table\", value: \"users\")\n\n// Perform the database operation\nlet users = await fetchUsers()\n\n// End the span when operation completes\nspan.end()\n```\n\n### Custom Log Example\n\nUse logs for point-in-time events ([read more](https://opentelemetry.io/docs/concepts/signals/logs/)). **Warning:** log `eventName` must be set for successful ingestion.\n\n```swift\n// Example: a user login can be recorded as a log record.\nimport AwsOpenTelemetryCore\nimport OpenTelemetryApi\n\n// Get the configured logger\nlet logger = AwsOpenTelemetryAgent.getLogger()\n\n// Log a login event\nlogger.logRecordBuilder()\n    .setEventName(\"user.login\") // `eventName` is REQUIRED\n    .emit()\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed testing instructions, development setup, and contributor guidelines.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-observability%2Faws-otel-swift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-observability%2Faws-otel-swift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-observability%2Faws-otel-swift/lists"}