Objectives

An Objective is a Service Level Objective: a target evaluated against an Indicator. It pairs a plain-English promise to your users (the description) with a machine-checkable target (the definition), and Firetiger evaluates it continuously, opening Investigations when the target is at risk.

Service: firetiger.observability.v1.ObjectivesService

Resource name pattern: objectives/{objective}

Access: Read-write

Methods

RPC	HTTP
CreateObjective	POST /v2/objectives
GetObjective	GET /v2/{name=objectives/*}
EvaluateObjective	GET /v2/{name=objectives/*}:evaluate
ListObjectives	GET /v2/objectives
UpdateObjective	PATCH /v2/{objective.name=objectives/*}
DeleteObjective	DELETE /v2/{name=objectives/*}
PromoteObjective	POST /v2/{name=objectives/*}:promote
AcceptObjective	POST /v2/{name=objectives/*}:accept
ArchiveObjective	POST /v2/{name=objectives/*}:archive
RestoreObjective	POST /v2/{name=objectives/*}:restore

Request/response shapes are in proto/firetiger/observability/v1/objectives.proto.

Objective resource

Field	Type	Behavior	Description
name	string	Output only	Format: objectives/{objective}
display_name	string	Required	Short label shown in lists and headers
description	string	Required	One-sentence, plain-English promise to the user (avoid SRE jargon)
indicator	string	Required	The Indicator this Objective is computed against. Format: indicators-v2/{indicator}
definition	oneof gauge | ratio	Required	Kind-specific SLO body; exactly one variant, and it must match the Indicator’s kind. The target (GAUGE threshold, RATIO target_failure_rate) lives inside the variant
filter	DimensionFilter[]	Optional	Narrows included rows to a subset of the Indicator’s declared dimension values. Filters do not define whether a dimension matters
owner_resource	string	Optional	Catalog resource this Objective belongs to (MVP: services/{service})
state	ObjectiveState	Output only	Lifecycle state. CALIBRATING on create (unless calibration_config.skip); promoted to ACTIVE via PromoteObjective. Agent-recommended Objectives persist in RECOMMENDED until accepted. See ObjectiveState
calibration_config	CalibrationConfig	Optional	Set skip = true to start ACTIVE with no calibration phase
calibration_observations	CalibrationObservations	Output only	Rolling daily baseline snapshots (≤7, FIFO) gathered while CALIBRATING; frozen on promotion
trigger	ObjectiveTrigger	Optional	What opens an Investigation against this Objective. A default RateMultiplierTrigger is applied on create when unset
latest_evaluation	LatestObjectiveEvaluation	Output only	Latest persisted health snapshot written by the periodic evaluator. Includes bounded per-Cell health rows, aggregate health counts, evaluation time, and any google.rpc.Status execution error
expert_session	string	Output only	The per-Objective objective-expert agent session that owns this Objective’s Indicator lifecycle (review, re-validation, repair). Format: agents/{agent}/sessions/{session}
recommendation_confidence	ObjectiveRecommendationConfidence	Optional	Agent’s confidence in this recommendation. See ObjectiveRecommendationConfidence
recommendation_evidence	string[]	Optional	Supporting evidence the agent cited when recommending this Objective
recommendation_reasoning	string	Optional	Free-text rationale for why this Objective was recommended
etag	string	Output only	Optimistic-concurrency token; required on Update, stale etags fail with ABORTED
create_time / update_time / delete_time	timestamp	Output only	Standard AIP lifecycle timestamps

UpdateObjective is field-masked: send the Objective with an update_mask of the paths to write. Output-only fields (state, calibration_observations, latest_evaluation, expert_session, etag, timestamps) are server-managed and ignored on Create/Update.

ObjectiveState

Value	Description
OBJECTIVE_STATE_UNSPECIFIED	Default zero value; not a valid persisted state
OBJECTIVE_STATE_CALIBRATING	Set on create (unless calibration_config.skip); gathers baseline samples but does not alert. Transitions to ACTIVE only via PromoteObjective
OBJECTIVE_STATE_ACTIVE	Evaluating and alerting
OBJECTIVE_STATE_INACTIVE	Customer-paused; not evaluating
OBJECTIVE_STATE_RECOMMENDED	Persisted agent recommendation. Visible in the Service UI but does not calibrate, evaluate, alert, or spin up an objective-expert session until accepted
OBJECTIVE_STATE_ARCHIVED	Dismissed recommendation. Hidden from active views and skipped by AcceptService bulk-activation

ObjectiveRecommendationConfidence

Value	Description
OBJECTIVE_RECOMMENDATION_CONFIDENCE_UNSPECIFIED	Confidence not set
OBJECTIVE_RECOMMENDATION_CONFIDENCE_HIGH	High confidence
OBJECTIVE_RECOMMENDATION_CONFIDENCE_MEDIUM	Medium confidence
OBJECTIVE_RECOMMENDATION_CONFIDENCE_LOW	Low confidence

Recommendation lifecycle

Beyond the customer-authored Create → calibrate → promote path, Objectives can be proposed by a Service’s expert agent. A recommended Objective is persisted as a real objectives/{objective} resource in OBJECTIVE_STATE_RECOMMENDED: it shows up in the Service UI alongside active Objectives but does not calibrate, evaluate, alert, or create an objective-expert session.

• AcceptObjective promotes a RECOMMENDED Objective into the normal lifecycle (entering CALIBRATING, or ACTIVE if calibration is skipped), spinning up its expert session.
• ArchiveObjective dismisses a recommendation into OBJECTIVE_STATE_ARCHIVED. Archived Objectives are hidden from active views and skipped by AcceptService bulk-activation.
• RestoreObjective brings an archived Objective back to RECOMMENDED.

Recommendation metadata (recommendation_confidence, recommendation_evidence, recommendation_reasoning) is carried on the Objective resource itself.

Dimensional evaluation

Objective dimensionality comes from the backing Indicator:

• If Indicator.dimensions is empty, the Objective is scalar.
• If Indicator.dimensions contains ServiceDimensions, Firetiger evaluates the Objective independently for each observed Cell. A Cell is the set of observed ServiceDimension values for that row, such as region=us-west-2 and tenant=acme-corp.
• Objective.filter[] narrows which rows are included before evaluation; it does not change which bound dimensions define the Cells.

Unhealthy dimensional Cells do not create one Investigation per Cell. Firetiger creates at most one Objective-level Investigation per cooldown window and includes the unhealthy Cells as evidence.

EvaluateObjective returns the current health on demand. The response contains health_status, summary, and cell_evaluations; scalar Objectives return one Cell with empty dimensions, while dimensional Objectives return one row per observed Cell with dimension values, health status, long/short observed values, target, row count, and ratio total events when applicable.

The periodic evaluator writes the same bounded health shape to Objective.latest_evaluation so readers can render current health without running a fresh Indicator query:

Field	Type	Description
health_status	ObjectiveHealthStatus	Overall Objective health: OBJECTIVE_HEALTH_STATUS_HEALTHY, OBJECTIVE_HEALTH_STATUS_UNHEALTHY, or OBJECTIVE_HEALTH_STATUS_NO_DATA
summary	ObjectiveHealthSummary	Aggregate counts: unhealthy, healthy, and no_data
evaluation_time	timestamp	Time the evaluator produced this snapshot
cell_evaluations	ObjectiveCellEvaluation[]	Bounded, priority-sorted per-Cell rows. Truncated snapshots set cell_evaluations_truncated = true
total_cells	int32	Full number of Cells evaluated before truncation
cell_evaluations_truncated	bool	True when the server kept only the highest-priority Cell rows
execution_status	google.rpc.Status	Set when evaluation failed; nil or OK means the snapshot ran successfully

ObjectiveHealthStatus

Value	Description
OBJECTIVE_HEALTH_STATUS_UNSPECIFIED	Default zero value; not a persisted health state
OBJECTIVE_HEALTH_STATUS_HEALTHY	No evaluated Cell is unhealthy and at least one Cell has data
OBJECTIVE_HEALTH_STATUS_UNHEALTHY	At least one Cell crossed the Objective target in both long and short windows
OBJECTIVE_HEALTH_STATUS_NO_DATA	No usable evaluation data, or evaluation could not produce a health result

Calibration and promotion

New Objectives start in CALIBRATING: the evaluator gathers up to seven daily baseline snapshots so the UI can suggest a confident threshold, but no Investigations are triggered yet. Promotion to ACTIVE is customer-driven via PromoteObjective (which can also apply a threshold_override atomically). Pass calibration_config.skip = true on create to start ACTIVE immediately.