12. Remote configuration

OpenTelemetry has no remote configuration for apps (OpAMP targets agents and collectors), so the profile defines a small one. It changes sampling, capture and masking without an app release, and can stop an SDK in an incident.

12.1 Fetching

• MUST fetch the policy with GET /v1/policy from the configuration host, sending Apsio-App-Key and the SDK’s name and version in User-Agent.
• MUST send If-None-Match with the last ETag it received; the backend answers 304 when nothing changed.
• MUST fetch at launch and then at most every 15 minutes in the foreground (the policy’s fetch_interval_seconds may lengthen this, never shorten it below 60 seconds).
• MUST cache the last policy on disk and use it at the next launch until a fetch succeeds.
• MUST use the defaults of this profile when it has never received a policy, or the policy fails validation.
• A backend MUST answer with a policy of safe defaults when the app has none configured, never with an error.

12.2 The document

A JSON object, validated by schemas/v0.1/policy.schema.json:

{
  "version": 7,
  "kill_switch": false,
  "fetch_interval_seconds": 900,
  "sampling": { "session_rate": 0.25, "replay_rate": 0.1 },
  "session": { "background_timeout_seconds": 1800, "max_length_seconds": 14400 },
  "queue": { "max_age_seconds": 604800 },
  "capture": {
    "replay": true,
    "network_spans": true,
    "logs_min_severity": "INFO"
  },
  "masking": { "mask_classes": [], "hide_classes": [] }
}

• version increases with each change. An SDK MUST ignore a policy whose version is lower than the one it has.
• Unknown fields MUST be ignored, so newer backends can add fields.
• masking and sampling.replay_rate can only tighten (section 10.5). An absent field tightens nothing. A backend MUST omit masking.text unless the app’s owner chose to force it: "all" voids every unmask the app set, so a default of "all" would undo them all.
• A backend that lets the app’s owner set masking.mask_classes or masking.hide_classes SHOULD warn, when the owner names a class, that a minified Android app must keep that class’s name (-keepnames) and a Swift class needs its module prefix: a name that does not resolve in the app records every session with replay in strict mode (10.4).
• capture can turn collection off or narrow it; it MUST NOT turn on capture the app turned off in code.

12.3 Kill switch

• When kill_switch is true, the SDK MUST stop collecting, drop its queue and send nothing until a later policy turns it off. It keeps fetching the policy at the normal interval.
• The kill switch takes effect at the next successful fetch.