Create Metric

Create Metric

Create an FME metric definition, with guidance on what makes a good metric and what to measure. Resolves traffic types and events against real data and asks the user to select an owner instead of guessing IDs. Owner existence is validated by the API on creation/readback; the declared tools do not provide an owner-directory lookup. Design guidance lives in metric-design.md. Related: /manage-experiments attaches metrics; /instrument-metric adds tracking calls.

For every phase marked Stop condition, see stop-conditions.md before improvising.

Tools

Works through the Harness MCP server or the Harness CLI; names are from tool-map.md.

Instructions

Phase 1: Establish scope

See scope-establishment.md. Confirm organization and project before any list or get operation — this is the Harness org/project, independent of the local application repo's name or git remote; never infer scope from the repo you're reading code in. If /choose-metric already ran and found no suitable metric, reuse its context (hypothesis, traffic type).

Phase 2: Understand the intent

What decision does the metric support (experiment primary / guardrail / supporting, or rollout monitoring)? What should change in which direction? Reuse /choose-metric context if it ran. If the user doesn't know what to measure or asks for suggestions, run Suggest metrics from code, show the coverage table, and let them pick one metric per pass. Pick the shape by asking the plain questions from Intent to configuration ("how many times?", "did they at least once?", "how much / how long?"), not by asking for aggregation names.

Phase 3: Check for an existing metric first

List metrics with full definitions, narrowed by name substring and traffic type if known — you need aggregation and baseEventTypes to judge duplicates. Read naming and tag conventions from this list. The backend returns 409 for a duplicate name or duplicate definition (same attribute combination under a different name). Catching this early saves a round trip. Check for auto-created - Split Agents metrics before creating a latency or error metric. If something close exists, confirm a new metric is actually needed rather than reusing/updating the existing one.

Stop condition if the request is vague (e.g. "track checkouts" with no aggregation specified) — see Ambiguous metric intent.

Phase 4: Resolve trafficType

List traffic types and use the traffic type name (immutable after creation, like name itself). Don't ask the user for an ID — resolve it from this list.

Phase 5: Resolve baseEventTypes[].eventTypeId

List event types narrowed by traffic type and event name if the user named one. The event name filter is a case-insensitive substring match; the traffic type filter accepts an ID or exact name, not a substring. Check pagination before treating a list as complete; use Get event type for an agreed exact name and verify the returned trafficTypes includes the intended type. Note: RUM/integration events may flow with no track() in code.

Stop condition if the event isn't in this list, or if several events match and none is an exact match for what the user said — a substring search on a word like purchase routinely returns a dozen variants, so present the real ones and ask instead of picking the shortest or cleanest-looking name. Don't invent an ID and don't silently substitute the closest-looking real event; see Missing or ambiguous event. If instrumentation is needed, settle the aggregation/value contract and applicable property filters below before handing off. Pass scope, environment, exact event name, traffic type, units, value source and required properties; resume here with that same contract plus code-test and delivery evidence, not just a success claim.

Phase 6: Decide aggregation, format, isPositive

Start from the matching row in the intent table. Key details:

• aggregation: COUNT, TOTAL, AVERAGE, RATE — see intent table for which fits.
• spread: not part of create body — every new metric is PER. Don't include it.
• format: NUMBER, DOLLAR, PERCENTAGE, SECONDS, MILLISECONDS, BYTES. RATE+PER coerces to PERCENTAGE.
• isPositive: true if increase is good. Drives significance-direction interpretation.
• baseEventTypes[].propertyForValue: for TOTAL/AVERAGE, the value can come from a named property on the event instead of the numeric track() value argument — set this when the user says the value lives in a property (e.g. order_total) rather than being passed positionally.
• Cap recommended for TOTAL/AVERAGE on unbounded values (revenue, durations) — reduces noise from heavy users.

This is the event contract (trafficType, aggregation, value units, value-vs-propertyForValue, and any required properties) that /instrument-metric must match exactly — if the event isn't instrumented yet, settle this contract now so the tracking call isn't written against a guess.

Phase 7: Name, description, and owners

• name: must match ^[A-Za-z][-_A-Za-z0-9]*$, max 100 chars, immutable. No spaces — if the user gives a human title, derive a valid name and confirm. Follow observed naming convention from Phase 3.
• description: what is counted, where event fires, which direction is good.
• owners: required; {type: "USER", email} or {type: "GROUP", identifier} (group's id field, not display name).

Stop condition if no owner was specified, or one turns out to be invalid — see Missing or invalid owner. Don't claim the owner was directory-verified without an actual lookup.