<!--
{
  "availability" : [
    "iOS: 27.0.0 -",
    "macOS: 27.0.0 -",
    "tvOS: 27.0.0 -",
    "visionOS: 27.0.0 -",
    "watchOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "StateReporting",
  "identifier" : "/documentation/StateReporting",
  "metadataVersion" : "0.1.0",
  "role" : "Framework",
  "symbol" : {
    "kind" : "Framework",
    "modules" : [
      "StateReporting"
    ],
    "preciseIdentifier" : "StateReporting"
  },
  "title" : "StateReporting"
}
-->

# StateReporting

Communicate your app’s state to the system to improve diagnostic actionability.

## Overview

StateReporting lets you define named domains and emit structured state transitions from your app. <doc://com.apple.documentation/documentation/MetricKit> surfaces state context in both state-aggregated and interval-level metric entries. Instruments displays transitions in the Points of Interest instrument so you can cross-reference app state against other profiling data.

Each domain holds up to one active state at a time, and you can combine states across domains. For example, your game can track its graphics configuration in one domain and its game mode in another, so you can compare performance across every state combination.

## Topics

### Essentials

[Getting started with StateReporting](/documentation/StateReporting/getting-started-with-statereporting)

Define reportable metadata types, obtain a state reporter for your domain, and report transitions at the right call sites in your app.

### Reporting

[`StateReporter`](/documentation/StateReporting/StateReporter)

An object unique per domain that records state transitions and volatile metadata updates.

[`SRStateReporter`](/documentation/StateReporting/SRStateReporter)

An object unique per domain that records state transitions and volatile metadata updates.

### Defining metadata

[`ReportableMetadata`](/documentation/StateReporting/ReportableMetadata)

A protocol for types that can supply their metadata as a dictionary of reportable values.

[`ReportableMetadataValue`](/documentation/StateReporting/ReportableMetadataValue)

A value in a reportable-metadata dictionary.

### Metadata type macros

[`ReportableMetadata()`](/documentation/StateReporting/ReportableMetadata())

Automatically generates `ReportableMetadata` conformance for a type.

[`ReportableMetadataKey(_:)`](/documentation/StateReporting/ReportableMetadataKey(_:))

Specifies a custom key name for a property in the generated `metadataDictionary`.

[`ReportableMetadataIgnored()`](/documentation/StateReporting/ReportableMetadataIgnored())

Excludes a property from the generated `metadataDictionary`.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)