sdk/fidl/fuchsia.power.observability/constants.fidl

// Copyright 2024 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

/// Cross-language shared constants for tracking observability in inspect.
///
/// The constants below are inspect keys. We name them so that the names shown
/// in Inspect output associate well with their meaning.
///
/// Some conventions used for uniform reporting:
/// - All timestamps are expressed in nanoseconds, and suffixed with "_ns".
/// - All durations are expressed in nanoseconds, and suffixed with "_ns".
/// - All plain counters are suffixed with `_count`.
/// - All node constant names are suffixed with `_NODE`.
@available(added=HEAD)
library fuchsia.power.observability;

// Inspect nodes of suspend hierarchy.

/// Label of an inspect node tallying suspend events.
const SUSPEND_EVENTS_NODE string = "suspend_events";

/// Label of an inspect node keeping suspend statistics.
const SUSPEND_STATS_NODE string = "suspend_stats";

/// Label of an inspect node tracking boot vs monotonic timestamps.
const BOOT_TO_MONO_NODE string = "boot_to_monotonic_timeline";

// Lifecycle.

/// Timestamp in nanos for when at least one suspend blocker is acquired.
/// This occurs when an internal procedure needs to prevent suspension.
/// For example, when servicing a wake lease request, system-activity-governor
/// will acquire a suspend blocker for the lifetime of the wake lease token.
/// This prevents suspension even while the underlying power broker lease is
/// pending.
const SUSPEND_BLOCKER_ACQUIRED_AT string = "suspend_blocker_acquired_at_ns";

/// Timestamp in nanos for when the last suspend blocker is dropped.
const SUSPEND_BLOCKER_DROPPED_AT string = "suspend_blocker_dropped_at_ns";

/// Timestamp in nanos for when a wake lease was created.
const WAKE_LEASE_CREATED_AT string = "wake_lease_created_at_ns";

/// Timestamp in nanos for when a wake lease failed to be satisfied by power broker.
const WAKE_LEASE_SATISFACTION_FAILED_AT string = "wake_lease_satisfaction_failed_at_ns";

/// Timestamp in nanos for when a wake lease is satisfaction with power broker.
const WAKE_LEASE_SATISFIED_AT string = "wake_lease_satisfied_at_ns";

/// Timestamp in nanos for a wake lease is dropped.
const WAKE_LEASE_DROPPED_AT string = "wake_lease_dropped_at_ns";

/// Timestamp in nanos for when suspend requests will be blocked because a
/// suspend lock is acquired. This event occurs right before a request to the
/// suspend HAL is made.
const SUSPEND_LOCK_ACQUIRED_AT string = "suspend_lock_acquired_at_ns";

/// Timestamp in nanos for when a suspend lock is dropped. This event occurs
/// after a response from the suspend HAL is received and handled by SAG.
const SUSPEND_LOCK_DROPPED_AT string = "suspend_lock_dropped_at_ns";

/// Timestamp in nanos at which suspend was attempted.
const SUSPEND_ATTEMPTED_AT string = "attempted_at_ns";

/// Timestamp in nanos for resume, after a successful suspend.
const SUSPEND_RESUMED_AT string = "resumed_at_ns";

/// Timestamp in nanos for resume, after an unsuccessful suspend.
const SUSPEND_FAILED_AT string = "failed_at_ns";

/// Timestamp in nanos for when a suspend attempt was blocked internally.
/// Suspend may be repeatedly blocked until all suspend locks and suspend
/// blockers have been dropped.
const SUSPEND_ATTEMPT_BLOCKED_AT string = "attempt_blocked_at_ns";

/// The duration of time last spent in suspend.
const SUSPEND_LAST_TIMESTAMP string = "last_time_in_suspend_ns";

/// The total cumulative duration of time spent in suspend since boot.
const SUSPEND_CUMULATIVE_DURATION string = "total_time_in_suspend_ns";

/// The duration of time last spent in operations leading to suspend,
/// excluding the time actually spent suspended.
///
/// TODO: b/354239403 - make this string also end with `_ns` to be consistent
/// with the conventions above.
const SUSPEND_LAST_DURATION string = "last_time_in_suspend_operations";

/// The requested future system state.
const SUSPEND_REQUESTED_STATE string = "requested_power_state";

// Errors

/// The error code related to the last suspend operation.
const SUSPEND_LAST_FAILED_ERROR string = "last_failed_error";

// Counters

/// The number of successful suspends.
const SUSPEND_SUCCESS_COUNT string = "success_count";

/// The number of failed suspends.
const SUSPEND_FAIL_COUNT string = "fail_count";

// System Activity Governor (SAG)

// // SAG: Wake leases

/// The current state of wake leases, as tracked by SAG.
/// The wake lease event history is tracked separately in SUSPEND_EVENTS_NODE.
const WAKE_LEASES_NODE string = "wake_leases";

/// The name of the wake lease as requested by the client.
const WAKE_LEASE_ITEM_NAME string = "wake_lease_name";

/// The time since boot when the wake lease was created in nanoseconds.
const WAKE_LEASE_ITEM_NODE_CREATED_AT string = "wake_lease_created_at";

/// The type of wake lease.
const WAKE_LEASE_ITEM_TYPE string = "wake_lease_type";

/// Lease that blocks suspension of the hardware platform.
const WAKE_LEASE_ITEM_TYPE_WAKE string = "wake";

/// Lease that blocks the system from dropping below the Application Activity
/// 'Active' state.
const WAKE_LEASE_ITEM_TYPE_APPLICATION_ACTIVITY string = "application_activity";

/// The kernel object ID of the token vended to the client.
const WAKE_LEASE_ITEM_CLIENT_TOKEN_KOID string = "wake_lease_client_token_koid";

/// The status of the wake lease.
const WAKE_LEASE_ITEM_STATUS string = "wake_lease_status";

/// Lease requested in power broker is awaiting satisfaction in the power
/// topology.
const WAKE_LEASE_ITEM_STATUS_AWAITING_SATISFACTION string = "pending";

/// Lease requested in power broker is satisfied by the current state of the
/// power topology.
const WAKE_LEASE_ITEM_STATUS_SATISFIED string = "satisfied";

/// Lease requested in power broker failed to be satisfied.
const WAKE_LEASE_ITEM_STATUS_FAILED_SATISFACTION string = "failed";

/// The error message. For example, if the underlying power broker lease failed
/// to be satisfied.
const WAKE_LEASE_ITEM_ERROR string = "error";

// // SAG: Suspend callbacks

/// Timestamp in nanos, for the start of suspend callback processing.
/// Suspend is gated on phase completion.
/// Event is recorded in SUSPEND_EVENTS_NODE.
const SUSPEND_CALLBACK_PHASE_START_AT string = "suspend_callbacks_started_at_ns";

/// Timestamp in nanos, for the end of suspend callback processing.
/// Suspend is gated on phase completion.
/// Event is recorded in SUSPEND_EVENTS_NODE.
const SUSPEND_CALLBACK_PHASE_END_AT string = "suspend_callbacks_ended_at_ns";

/// Timestamp in nanos, for the start of resume callback processing.
/// Resume is not gated on phase completion.
/// Event is recorded in SUSPEND_EVENTS_NODE.
const RESUME_CALLBACK_PHASE_START_AT string = "resume_callbacks_started_at_ns";

/// Timestamp in nanos, for the end of resume callback processing.
/// Resume is not gated on phase completion.
/// Event is recorded in SUSPEND_EVENTS_NODE.
const RESUME_CALLBACK_PHASE_END_AT string = "resume_callbacks_ended_at_ns";

// // END SAG: Suspend callbacks

/// The name of current active wake locks, recorded when wake locks
/// become active and if we attempted to suspend, but failed because
/// there were active wake locks.
const ACTIVE_WAKE_LOCK_NAMES string = "active_wake_lock_names";

/// The name of current inactive wake locks, recorded when wake locks
/// become inactive and if we attempted to suspend, but failed
/// because there were active wake locks.
const INACTIVE_WAKE_LOCK_NAMES string = "inactive_wake_lock_names";

/// The number of current active epolls, recorded when epolls become
/// active / inactive and if we attempted to suspend, but failed
/// because there were active epolls.
const ACTIVE_EPOLLS_COUNT string = "active_epolls_count";

// Fuchsia Suspend HAL

/// The boot time captured after resuming from suspend, in nanoseconds.
const BOOT_TIME string = "boot_time_ns";

/// The delta between the boot and monotonic clocks after resuming from
/// suspend, in nanoseconds.
/// Formula: mono_time_ns = boot_time_ns - boot_monotonic_difference_ns
const BOOT_MONO_DIFF string = "boot_monotonic_difference_ns";

/// The boot timestamp in nanoseconds at which the wake reason report was
/// generated.
const WAKE_REASON_REPORT_TIME string = "wake_reason_last_report_time_ns";

/// The last reported number of potential wake sources for the last successful
/// wake.
const WAKE_REASON_WAKE_SOURCES_COUNT string = "wake_reason_last_wake_sources_count";

/// The last number of UNreported potential wake sources for the last successful
/// wake.
const WAKE_REASON_WAKE_SOURCES_UNREPORTED_COUNT string
        = "wake_reason_last_wake_sources_unreported_count";