Analysis Orchestrator

The Analysis Orchestrator runs analyzer plugins against artifacts automatically whenever an artifact's tags overlap an enabled policy's required tags. Use it when you want a repeatable rule — "every artifact tagged X should always get plugin Y" — instead of a one-off falcon analysis create.

When to use this vs. manual analysis create

Path	When	Trigger
falcon analysis create (manual)	A one-off analysis you control fully	You run the command
falcon analysis policy create (orchestrator)	A repeatable rule: every artifact tagged X gets plugin Y	The policy is enabled; the orchestrator runs it automatically

Both can target the same artifact independently. The two analyses get separate analysis_ids and separate output directories.

1. Discover available plugins

falcon analysis plugins list --scope BUILTIN

Common built-in plugins for orchestrator policies:

Plugin	Use
builtin:xprof-summary	Human + machine summary of XProf profile traces
precision-compare	Per-tensor/op precision delta between two artifacts
pallas-llo-analysis	Pallas kernel low-level operator breakdown
operator-analysis	Generic per-op time/cost analysis

Custom plugins are not created via a plugins create CLI verb (no such verb exists). They are implicitly upserted by the apiserver the first time you call falcon analysis create with an inline --command + declared outputs — a new plugin version is appended (or no-op'd if content hash unchanged). After that first upsert, the plugin appears under --scope CUSTOM and can be referenced by name from other analyses or policies.

2. Write a policy manifest

# my-xprof-policy.yaml
name: auto-xprof-on-operator-profiles
enabled: true
required_tags:                       # must overlap artifact.tags for a match
  - data:xplane
match_mode: any                      # `any` or `all` (lowercase)
plugin_names:
  - builtin:xprof-summary
analyzer_image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
max_retries: 0
description: Auto-summarize XProf for every operator-profile artifact

match_mode:

• any — qualify if at least one required_tag is in artifact.tags
• all — qualify only if every required_tag is in artifact.tags

3. Create the policy

falcon analysis policy create -f my-xprof-policy.yaml

POLICY_ID      NAME                             VERSION  ENABLED  MATCH_MODE  PLUGINS                IMAGE                                               MAX_RETRIES
ap-c817m52qpa  auto-xprof-on-operator-profiles  1        true     any         builtin:xprof-summary  gcr.io/google.com/cloudsdktool/google-cloud-cli...  0

The policy is active immediately. Within ~15 seconds the orchestrator sweeps all matching artifacts and starts minting analyses.

4. Observe orchestrator-driven analyses

Orchestrator-minted records appear in falcon analysis records with source: SYSTEM and a populated sar_name. Manual records have source: MANUAL and no sar_name.

falcon analysis records --exp-id <exp>

Status progresses PENDING → RUNNING → SUCCEEDED | FAILED exactly like manual analyses; falcon analysis get <id> works identically for both.

5. Inspect or update the policy

falcon analysis policy list
falcon analysis policy get <id-or-name>
falcon analysis policy update <id-or-name> --enabled false       # pause
falcon analysis policy update <id-or-name> --max-retries 3
falcon analysis policy delete <id-or-name> --yes                 # destructive

Spec-shape changes (plugin list, required tags, match mode) require policy delete + policy create -f new.yaml so you review the full manifest. In-flight analyses snapshotted against the old policy version keep running until they reach a terminal state — you can optionally --abort-prior-version-analyses during an update.

6. Add or change artifact tags

To make an existing artifact match a policy whose required_tags include loss-validation:

falcon artifact tag <artifact-id> --add loss-validation

Tags are additive (union); the orchestrator picks up the new tag on its next sweep.

Common failure modes

Symptom	Check
policy create: match_mode must be "any" or "all"	YAML used uppercase ANY; lowercase only
No SYSTEM record after ~30 s	Is the policy enabled: true? Do the tags actually overlap? (falcon analysis policy get, falcon analysis records)
Analysis stuck PENDING for >5 min	Likely a platform issue — file an issue and ping operators
policy create returns an analyzer_image validation error	The image must be a fully-qualified registry path (e.g. gcr.io/x/y:tag); short names aren't accepted

Concepts

• The orchestrator creates one SystemAnalysisRequest (SAR) per (policy, cluster, artifact) match. Each SAR mints one child analysis record per plugin in plugin_names.
• For the full orchestrator internals (reconciler chain, finalizer semantics), see the falcon-workflow orchestrator reference in the Falcon repository.

Scripting & automation

All commands above support --output json for scripts and CI. For example, capture the new policy id:

falcon analysis policy create -f my-xprof-policy.yaml --output json | jq -r .policy.policyId

Filter for orchestrator-minted records:

falcon analysis records --exp-id <exp> --output json | \
  jq '.records[] | select(.source == "SYSTEM") | {analysis_id, plugin_names, sar_name, status}'