# Native and mobile telemetry with Telemio

Telemio is OpenTelemetry-first on native clients. Use the platform's OpenTelemetry implementation for transport and runtime instrumentation, then keep the resulting traces connected to the services and agentic work the app calls.

## Security rule

Do not embed privileged Telemio server API keys in an iOS, Android, React Native, desktop, or other distributed client binary. Anything shipped to an end-user device should be assumed recoverable.

Use a client-safe collection path, a telemetry gateway/collector you control, or another ingestion path designed for distributed clients. Keep privileged credentials on trusted infrastructure.

## Swift and iOS

For Swift/iOS applications:

1. Initialize OpenTelemetry early in application startup.
2. Give the app stable service/application identity plus app version and build metadata.
3. Preserve screen/route, session, network, error/crash, and performance context where the libraries support it.
4. Propagate trace context on requests to your backend so a mobile interaction can continue into service traces.
5. Buffer or retry telemetry in a way that respects app lifecycle and intermittent connectivity.
6. Redact user-entered text, tokens, cookies, credentials, and other sensitive values before export.

Prefer platform-native OpenTelemetry libraries over a JavaScript bridge when the application is natively written in Swift.

## Android, Kotlin, and Java

For native Android applications:

1. Use the OpenTelemetry Android instrumentation/runtime appropriate to the project.
2. Initialize from the application's startup path before the important user flows begin.
3. Preserve application version, build, session, activity/screen, network, crash/ANR, and rendering/performance context where supported.
4. Propagate trace context to backend HTTP/gRPC requests.
5. Use offline buffering and lifecycle-aware export where the chosen instrumentation supports it.
6. Keep privileged backend credentials out of the APK/AAB.

Kotlin and Java application code can add manual OpenTelemetry spans for operations that matter to the product when automatic mobile instrumentation is too generic.

## React Native

Treat React Native as two related runtime surfaces:

- the JavaScript application runtime
- the native iOS/Android host and network/runtime layer

Avoid double-instrumenting the same network request. Pick one layer as the primary source for a signal, preserve shared trace/session identifiers, and use native instrumentation where it provides better lifecycle or performance context.

## What to correlate

A useful mobile trace should make it possible to follow:

```text
screen or user action
  -> mobile network request
    -> API service
      -> queue or database
      -> agent/model/tool work
      -> downstream service
```

Keep release/build identity on the mobile side and service/release identity on the server side so regressions can be tied to the code that changed.

## Privacy

Do not treat mobile telemetry as a place to copy form values, chat content, access tokens, payment information, or arbitrary local storage. Prefer low-cardinality operation names, stable identifiers, status, duration, release metadata, and explicitly reviewed attributes.