Services

The Services catalog is the system map agents use to reason about ownership, blast radius, and which components show up in a given Flow. Each Service entry carries a human description, an agent-authored deep-dive context, and the breakdown Dimensions its health is measured along.

Service: firetiger.observability.v1.ServiceCatalogService

Resource name pattern: services/{service_id}

Access: Read-write

Methods

The standard AIP-compliant CRUD surface plus a recommendation-lifecycle surface is available. Request/response shapes are in proto/firetiger/observability/v1/services.proto and follow the same patterns as other resources documented here (e.g. Tags).

Service methods

RPC HTTP
CreateService POST /v1/catalog/services
GetService GET /v1/catalog/{name=services/*}
ListServices GET /v1/catalog/services
UpdateService PATCH /v1/catalog/{service.name=services/*}
DeleteService DELETE /v1/catalog/{name=services/*}
RecommendService POST /v1/catalog/services:recommend
AcceptService POST /v1/catalog/{name=services/*}:accept
ArchiveService POST /v1/catalog/{name=services/*}:archive
RestoreService POST /v1/catalog/{name=services/*}:restore
RecommendServiceObservability POST /v1/catalog/{parent=services/*}:recommendObservability
RecreateServiceExpertSession POST /v1/catalog/{name=services/*}:recreateExpertSession

ServiceDimension methods

A ServiceDimension is a service-local health breakdown axis nested under a Service (services/{service}/dimensions/{dimension}). It replaces the deprecated top-level Service.dimensions list for Service observability: Objectives and Indicators bind to a ServiceDimension.

RPC HTTP
CreateServiceDimension POST /v1/catalog/{parent=services/*}/dimensions
GetServiceDimension GET /v1/catalog/{name=services/*/dimensions/*}
ListServiceDimensions GET /v1/catalog/{parent=services/*}/dimensions
UpdateServiceDimension PATCH /v1/catalog/{service_dimension.name=services/*/dimensions/*}
DeleteServiceDimension DELETE /v1/catalog/{name=services/*/dimensions/*}
AcceptServiceDimension POST /v1/catalog/{name=services/*/dimensions/*}:accept
ArchiveServiceDimension POST /v1/catalog/{name=services/*/dimensions/*}:archive
RestoreServiceDimension POST /v1/catalog/{name=services/*/dimensions/*}:restore

Recommendation lifecycle

Services and ServiceDimensions are both first-class catalog resources that carry a state, and both flow through the same recommendation lifecycle:

  • System discovery stores newly-discovered catalog entries via RecommendService. The recommended Service is persisted as a real resource in SERVICE_STATE_RECOMMENDED and its Service Expert is provisioned immediately.
  • Each Service’s Expert then proposes its breakdown dimensions, Objectives, and backing Indicators via RecommendServiceObservability. Recommended ServiceDimensions land in SERVICE_DIMENSION_STATE_RECOMMENDED.
  • A customer accepts a recommendation (AcceptService / AcceptServiceDimension) to promote it to the *_ACTIVE state, or archives it (ArchiveService / ArchiveServiceDimension) to dismiss it into the *_ARCHIVED state. Restore (RestoreService / RestoreServiceDimension) brings an archived resource back. User-created Services default to SERVICE_STATE_ACTIVE.
  • AcceptService bulk-activates the Service’s accepted breakdown and Objectives; archived child Objectives are skipped.

Recommendation metadata is carried on the resource itself: recommendation_confidence, recommendation_evidence, and recommendation_reasoning (see field tables below).

Service resource

Field Type Behavior Description
name string Output only Format: services/{service}
display_name string Required Short, scannable label shown in headers and Service lists (1–200 chars)
description string Optional One-paragraph, human-facing overview of what the Service is
context string Optional Long-form Markdown deep-dive read by agents (code paths, telemetry hints, oncall notes). Agent-proposed at accept time; customer-editable
expert_session string Output only The per-Service service-expert agent session that proposes and maintains this Service’s Objectives, Indicators, and Dimensions. Format: agents/{agent}/sessions/{session}
dimensions string[] Optional, deprecated The firetiger.dimensions.v1 Dimensions this Service’s health is broken down by — its declared deployment shape (e.g. environment, region, cloud). Each entry is a dimensions/{dimension} resource name. Superseded by the nested ServiceDimension resource; use CreateServiceDimension/ListServiceDimensions instead
state ServiceState Output only Lifecycle state. User-created Services default to SERVICE_STATE_ACTIVE; system-recommended Services persist in SERVICE_STATE_RECOMMENDED until accepted or archived. See ServiceState
recommendation_confidence RecommendationConfidence Optional Agent’s confidence in this recommendation. See RecommendationConfidence
recommendation_evidence string[] Optional Supporting evidence the agent cited when recommending this Service
recommendation_reasoning string Optional Free-text rationale for why this Service was recommended
etag string Output only Optimistic-concurrency token returned by Get and required on Update; stale etags fail with ABORTED
create_time / update_time / delete_time timestamp Output only Standard AIP lifecycle timestamps

UpdateService is field-masked: send the Service with an update_mask listing the paths to write (e.g. context). state, expert_session, and the other output-only fields are server-managed and ignored on Create/Update.

ServiceDimension resource

Field Type Behavior Description
name string Output only Format: services/{service}/dimensions/{dimension}
display_name string Required Short, scannable label for the breakdown axis (1–200 chars)
description string Optional One-line, human-facing description of what this axis splits on
state ServiceDimensionState Output only Lifecycle state. Recommended dimensions persist in SERVICE_DIMENSION_STATE_RECOMMENDED until accepted or archived. See ServiceDimensionState
source_column string Optional Suggested or observed query output column for this axis. Indicator DimensionBindings still carry the authoritative per-query column mapping; this lets the Service page preview recommended dimensions before an Objective is opened
recommendation_confidence RecommendationConfidence Optional Agent’s confidence in this recommendation. See RecommendationConfidence
recommendation_evidence string[] Optional Supporting evidence the agent cited when recommending this dimension
recommendation_reasoning string Optional Free-text rationale for why this dimension was recommended
etag string Output only Optimistic-concurrency token returned by Get and required on Update; stale etags fail with ABORTED
create_time / update_time / delete_time timestamp Output only Standard AIP lifecycle timestamps

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

Enums

ServiceState

Value Description
SERVICE_STATE_UNSPECIFIED Default zero value; not a valid persisted state
SERVICE_STATE_RECOMMENDED System-recommended Service awaiting accept/archive
SERVICE_STATE_ACTIVE Accepted (or user-created) Service
SERVICE_STATE_ARCHIVED Dismissed recommendation; hidden from active views

ServiceDimensionState

Value Description
SERVICE_DIMENSION_STATE_UNSPECIFIED Default zero value; not a valid persisted state
SERVICE_DIMENSION_STATE_RECOMMENDED Recommended breakdown axis awaiting accept/archive
SERVICE_DIMENSION_STATE_ACTIVE Accepted dimension
SERVICE_DIMENSION_STATE_ARCHIVED Dismissed recommendation

RecommendationConfidence

Value Description
RECOMMENDATION_CONFIDENCE_UNSPECIFIED Confidence not set
RECOMMENDATION_CONFIDENCE_HIGH High confidence
RECOMMENDATION_CONFIDENCE_MEDIUM Medium confidence
RECOMMENDATION_CONFIDENCE_LOW Low confidence

Revision history (AIP-162)

Revision history is served by the legacy firetiger.objectives.v1.ServicesService, which exposes the same services/{service} resource plus two read RPCs. Every mutation (Create, Update, Delete, Undelete) atomically writes a revision row recording who changed the resource, what kind of change, and when.

ListServiceRevisions

List the revision history of one Service. Default order is reverse-chronological (newest first).

GET /v1/{parent=services/*}/revisions

or as a Connect RPC:

POST /firetiger.objectives.v1.ServicesService/ListServiceRevisions

Request body

Field Type Required Description
parent string Yes Resource name of the Service whose revisions to list. Format: services/{service}
page_size integer No Maximum revisions per page
page_token string No Token from a previous ListServiceRevisionsResponse
filter string No AIP-160 filter over name, revision_number, operation, actor_subject, actor_kind, create_time
order_by string No AIP-132 ordering. Defaults to create_time desc

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.objectives.v1.ServicesService/ListServiceRevisions" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"parent": "services/checkout-api", "page_size": 50}'

Response

{
  "serviceRevisions": [
    {
      "name": "services/checkout-api/revisions/3",
      "snapshot": { "name": "services/checkout-api", "displayName": "Checkout API v3", "...": "..." },
      "createTime": "2026-05-14T18:10:11Z",
      "operation": "REVISION_OPERATION_UPDATE",
      "actor": { "subject": "user_2abc", "kind": "ACTOR_KIND_USER" }
    }
  ],
  "nextPageToken": ""
}

GetServiceRevision

Return a single revision by its AIP-162 nested-collection name.

GET /v1/{name=services/*/revisions/*}

or:

POST /firetiger.objectives.v1.ServicesService/GetServiceRevision

Request body

Field Type Required Description
name string Yes Format: services/{service}/revisions/{n} where n is a positive integer

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.objectives.v1.ServicesService/GetServiceRevision" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "services/checkout-api/revisions/2"}'

Notes

  • History starts at opt-in time. Services that existed before this revision API shipped have no historical revisions until their next mutation.
  • Purge (force delete) cascades to revisions atomically.
  • See Flows for the same revision pattern applied to the Flows resource.
This site uses Just the Docs, a documentation theme for Jekyll.