Skip to content

AIFACTORY-FEAT-175: Observability libraries: the Factory telemetry conventions as one registration

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

A design artefact, not a tracker

This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).

Epic Ecosystem component extensions · Increment I0 Readiness · State elaborated · Route backend-developer · Phase before development · Build order 19 of 185 (Templates and libraries)

Before development

Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I0 are developed. The mark travels with every task (tag phase:before-development).

Sixty-plus Factory services emit traces, logs and metrics through the Extensions.Observability and Extensions.Telemetry libraries, which carry OpenTelemetry, health and metrics wiring but know nothing of a run, a step, an attempt, an agent, a tenant or a project. Without a shared convention each service would write its own enricher and the Studio and the dashboards would correlate nothing. The libraries gain one registration that enriches every signal from the scope accessor and the run event envelope, the health and meter conventions the worker and aggregator templates already follow, and the rule of ADR-0019 that no prompt, completion or tool output reaches telemetry by default. Component: Observability libraries (extend).

Delivers —
Stubs —
Realizes components: cmp-observability
adrs: ADR-0014, ADR-0018, ADR-0019
Requirements —
Depends on AIFACTORY-FEAT-090 Contracts package from the published schemas
Sources model/components.yaml, docs/architecture/adr/0019-data-governance.md, docs/architecture/adr/0018-nfr-baseline.md

AIFACTORY-US-257: Observability libraries: one registration puts the scope on every activity and log record, the agent inside an agent host, and tenant and project on every instrument recorded through its helper

enabling · persona platform-admin As a platform admin, I want one telemetry registration that reads the Factory scope and enriches every signal of a service, so that no Factory service writes its own enricher and a run can be followed across services under the same attribute names.

The Features page of the Observability library lists what the library holds today: option classes for OpenTelemetry, the stack and the backends, their validators, the option registrations AddObservabilityStackOptions, AddObservabilityBackendOptions and AddOpenTelemetryOptions, and the attribute name constants of OpenTelemetryAttributeName. The Overview page of the Telemetry library describes a latency exporter that tags the current activity and logs under a scope. Neither library knows a tenant, a project, a run, a step, an attempt or an agent, which ADR-0014 decision 1 names as the identity of every Factory event and ADR-0015 decision 2 requires on every contract. This PBI delivers the single enrichment registration that decision D114 placed in increment I0, so that the Factory profile of the base template (AIFACTORY-US-229) can pin it. A host makes one call of the registration in ConnectSoft.Extensions.Observability. The call installs enrichers that live in ConnectSoft.Extensions.Telemetry and read the scope from the one accessor of ConnectSoft.Extensions.AI.Factory.Abstractions, which AIFACTORY-US-220 of the feature component-extensions-ai delivers. The libraries take the abstractions package by a version pin and define no scope type of their own. The attribute names are the ones docs/planes/trust-operations/observability/observability.md fixes for the spans and metrics of the Factory: connectsoft.factory.tenant_id, connectsoft.factory.project_id, connectsoft.factory.run_id, connectsoft.factory.step_id, connectsoft.factory.attempt_id and connectsoft.factory.agent_id. They exist once, as constants beside OpenTelemetryAttributeName, and the first five map to the envelope fields tenantId, projectId, runId, stepId and attemptId of the contracts package. Every activity started while a scope is established and every log record written under it carries the first five; an identifier the scope does not hold, such as the run outside a run, is absent and never an empty value. The agent identifier is no part of the scope of the accessor. The trace context of the pinned abstractions package, AgentTraceContext, holds it as the agent origin, so the library offers one method that an agent host calls with the trace context of a request, as the generated agent host of AIFACTORY-US-144 does, and only while that call is in effect the enrichers write connectsoft.factory.agent_id as well; a service that is no agent host never calls it and the attribute is absent. The workflow, which the migrated text listed beside the agent, is no identity of the envelope and gets no scope attribute: a service that needs it records it as the metric dimension workflow, the name the metrics of model/services use, and the library holds that key and the key agent as constants only. The other attributes the observability page lists, such as the model profile and the tool identifier, belong to the spans of the agent runtime and of tool calls and are not written by this registration. Metrics are tagged where they are recorded. A .NET meter has no hook that adds a tag to a measurement after it was recorded, and the Metrics catalog page of the Telemetry library requires no OpenTelemetry reference, so a scope tag provider returns the tags of the current scope filtered by an allowlist of the options, and an instrument helper built on IMeterFactory creates the counters, histograms and gauges that record through it. The tag keys are tenant and project, the dimension names model/services gives its metrics. By default the provider returns these two only, because the catalog page treats unbounded label values as a cardinality risk; run, step and attempt travel on activities and log records and reach a measurement only when the allowlist names them (D115). The Factory preset of AIFACTORY-US-229 keeps the default allowlist, so a generated service does not carry the three on every metric, and a service that needs one of them on a series names it in the allowlist of its own options. A meter of a library or of the runtime, which does not record through the helper, is not tagged. When no scope is established, at start-up or on a health probe, the enrichers and the provider add nothing and the typed exception of the accessor never reaches the host. A second call of the registration has no effect: the enrichers are registered once.

Acceptance criteria

AC1 Given a host that calls the single registration and establishes a scope through the middleware of the pinned abstractions package, when a REST call, a gRPC call and a message handler each start an activity and write a log record, then the exported activity and the log record carry connectsoft.factory.tenant_id, connectsoft.factory.project_id, connectsoft.factory.run_id, connectsoft.factory.step_id and connectsoft.factory.attempt_id with the values of the accessor, the names docs/planes/trust-operations/observability/observability.md lists, and an identifier the scope does not hold is absent and not an empty value (ADR-0014 decision 1, ADR-0015 decision 2).
AC2 Given an instrument created through the instrument helper and a measurement recorded while a scope is established, when it is exported, then it carries the tags tenant and project, the dimension names of model/services, and no run, step or attempt tag unless the allowlist of the options names that identifier; given the allowlist names all three, then the measurement carries them, and the Factory preset of AIFACTORY-US-229 leaves the allowlist at its default; a measurement of a meter that does not record through the helper carries no scope tag, so that the label cardinality of the series the objectives of model/nfr-targets.yaml are evaluated from stays a decision of the options (ADR-0018).
AC3 Given no scope is established, at start-up or on a health probe, when an activity starts, a log record is written and a measurement is recorded through the helper, then no scope attribute or tag is added and no exception leaves the enrichers or the provider; given the registration is called twice, then the enrichers are registered once and each attribute appears once on a signal (ADR-0015 decision 2 keeps the accessor as the only source of the scope).
AC4 Given the scope attribute name constants, when the contract test runs against the pinned contracts package, then the six constants equal the names docs/planes/trust-operations/observability/observability.md lists, the first five map one to one to the envelope fields tenantId, projectId, runId, stepId and attemptId of docs/reference/schemas/run-event-envelope.schema.json, and an architecture test finds the scope type only in the pinned abstractions package and none in the two library solutions (ADR-0014 decision 1).
AC5 Given an agent host that calls the trace context method of the library with an AgentTraceContext whose agent origin is set, when an activity starts and a log record is written inside that call, then both carry connectsoft.factory.agent_id with the agent origin beside the scope attributes; outside the call, and in a host that never makes it, the attribute is absent, and no signal carries a workflow attribute from this registration (ADR-0014 decision 1, docs/planes/trust-operations/observability/observability.md).
Traces: descriptors execution-scope-v1, run-event-envelope-v1
Traces: adrs ADR-0014, ADR-0015, ADR-0018
Relates: nfrs NFR-10
Depends on feature:component-extensions-ai, feature:contracts-package
Sources model/components.yaml, model/nfr-targets.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/reference/schemas/run-event-envelope.schema.json, docs/planes/trust-operations/observability/observability.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1178 Scope attribute name constants and the signature of the single registration contract A nested group of OpenTelemetryAttributeName holds the six scope attribute names connectsoft.factory.tenant_id, connectsoft.factory.project_id, connectsoft.factory.run_id, connectsoft.factory.step_id, connectsoft.factory.attempt_id and connectsoft.factory.agent_id and the metric dimension keys tenant, project, run, step, attempt, agent and workflow as constants; the single registration is one extension method with an options type that holds the metric tag allowlist; a contract test compares the six names with docs/planes/trust-operations/observability/observability.md and maps the first five to the envelope fields of the pinned contracts package (docs/reference/schemas/run-event-envelope.schema.json). ConnectSoft.Extensions.Observability
AIFACTORY-TASK-632 Factory enrichment of traces, logs and metrics implementation Enrichers in ConnectSoft.Extensions.Telemetry read the scope from the accessor of the pinned ConnectSoft.Extensions.AI.Factory.Abstractions package and add the tenant, project, run, step and attempt attributes to every activity and log record, and the agent attribute while the trace context method is in effect; a scope tag provider returns the tags tenant and project of the current scope, and run, step and attempt only when the allowlist names them; an instrument helper built on IMeterFactory creates the instruments that record through the provider; an identifier the scope does not hold is absent, an absent scope adds nothing, the exception of the accessor is not propagated, and a meter that does not use the helper is not tagged. ConnectSoft.Extensions.Telemetry
AIFACTORY-TASK-1179 Single registration that installs the enrichers once implementation One extension method of ConnectSoft.Extensions.Observability installs the activity and log enrichers, the scope tag provider and the instrument helper of the Telemetry library and binds its options; a second call registers nothing more, and the Getting Started page of the library shows the one call a host makes and how it creates an instrument through the helper. ConnectSoft.Extensions.Observability
AIFACTORY-TASK-1180 Verify the registration over REST, gRPC and a message handler in the Observability solution verification Run dotnet test -c Release --no-build on the solution of ConnectSoft.Extensions.Observability; the tests with an in-memory exporter over a REST call, a gRPC call and a message handler, the double registration test and the constant mapping test pass and prove AC1, AC3 and AC4 of AIFACTORY-US-257 (ADR-0014, ADR-0015). ConnectSoft.Extensions.Observability
AIFACTORY-TASK-1289 Verify the enrichers, the scope tag provider and the instrument helper in the Telemetry solution verification Run dotnet test -c Release --no-build on the solution of ConnectSoft.Extensions.Telemetry; the enricher tests, the absent-scope test, the helper tests with the default and the extended allowlist, the test of a meter that does not use the helper and the agent attribute test pass and prove AC2, AC3 and AC5 of AIFACTORY-US-257 (ADR-0014, ADR-0018). ConnectSoft.Extensions.Telemetry

AIFACTORY-US-258: Observability libraries: the ready and live health tags, the declared connectsoft. meter names and the drain, backlog and lease series are one convention with a conformance test package

enabling · persona platform-admin As a platform admin, I want the health tags, the meter names and the background work series of a service stated once and checked by a shared test package, so that dashboards, probes and objectives read the same names from every Factory service.

The conventions a Factory service follows for health and meters exist today only as habits of single repositories. The Features page of the health checks library tags its self check as live. The Configuration page of the worker template fails readiness on the tag ready while the worker drains or its work in flight exceeds BacklogThreshold, and the worker and aggregator templates publish drain, backlog and lease series. The Health Checks page of the base template registers its resource utilization, disk storage, memory and Hangfire checks under other tags only (resource utilization, diskstorage, memory, application hangfire). The Metrics catalog page of the Telemetry library names its own meter ConnectSoft.Extensions.Telemetry and asks that the catalog stay aligned when a metric is renamed. The model names every metric of a Factory service connectsoft.factory.<area>.<metric>, for example connectsoft.factory.usage.cost_usd of CostUsageService, and one service may hold more than one area: RunControlService has metrics under connectsoft.factory.runs and under connectsoft.factory.attempts. ADR-0018 sets objectives per service class, and nothing can evaluate them across sixty services unless the names agree. This PBI states the convention once in the Observability library. Constants name the two health tags. A check that must gate a probe carries one of them; a check with neither tag is informational, is reported by neither probe and is listed as such, so the inherited checks of the base template stay valid without a retag. A service declares its meter names through a helper: a name is lower case, dotted and starts with connectsoft.; under the Factory profile it is the connectsoft.factory.<area> prefix that model/services gives the metrics of that service, and a service may declare more than one; the template habit connectsoft.<service>, for example connectsoft.workertemplate, stays valid for other generations. Every instrument of a declared meter sits under the declared name and has a unit. The drain, backlog and lease series that a service with a background loop publishes get fixed names, units and tag sets. A convention page of the library documents the three. A conformance test package is published beside the library, and a service references it from its architecture tests. It fails a check with neither tag that a probe reports, a meter created by an assembly of the solution under a name that was not declared, an instrument of the solution that lies outside its declared name, has no unit or was not created through the instrument helper of AIFACTORY-US-257, a service with a background loop that lacks one of the three series, and a type in the solution that enriches a signal with a scope attribute of its own, which is the check the base template plants in its Factory preset. Meters of libraries and of the runtime are outside the assertion, with ConnectSoft.Extensions.Telemetry as the example. The test checks the shape of a declared meter name and does not compare the declared names with the model of a service. Each failure names the offending check, meter, instrument or type.

Acceptance criteria

AC1 Given a service that registers its health checks with the tag constants of the library, when the liveness and the readiness endpoints are probed, then liveness reports the checks tagged live and readiness the checks tagged ready; a check with neither tag, such as the resource utilization, disk storage, memory and Hangfire checks the base template registers, is reported by neither probe and listed by the conformance test as informational, and the test fails only when a probe reports a check without its tag, and names the check (ADR-0018, docs/architecture/nfr-baseline.md).
AC2 Given a service that declares its meter names through the helper and has a background loop, when the conformance test runs, then it passes when every declared name is lower case, dotted and starts with connectsoft., every meter created by an assembly of the solution has a declared name, every instrument sits under a declared name with a unit, and the drain, backlog and lease series exist with the names, units and tags of the convention page; one service that declares connectsoft.factory.runs and connectsoft.factory.attempts passes, as model/services/control-plane/RunControlService.yaml names its metrics, a meter of a library such as ConnectSoft.Extensions.Telemetry is not examined, and an undeclared meter, an instrument outside its declared name or a missing series fails the test with its name (ADR-0018, model/nfr-targets.yaml).
AC3 Given a solution that defines an enricher which writes a tenant, project, run, step, attempt or agent attribute of its own, or an instrument that was not created through the instrument helper, when the conformance test runs, then it fails and names the type or the instrument, so that the single registration stays the only source of the scope attributes and tags (ADR-0014 decision 1).
AC4 Given the convention page of the library, when it is compared with the constants and with the conformance test package, then every tag, meter rule and series the page names is a constant or an assertion of the package, which closes the health and meter part of the need model/components.yaml records for this component; the enrichment part of that need, the agent identifier included, is closed by AIFACTORY-US-257 (ADR-0018).
Traces: adrs ADR-0014, ADR-0018
Relates: nfrs NFR-17
Sources model/components.yaml, model/nfr-targets.yaml, model/services/control-plane/RunControlService.yaml, model/services/control-plane/CostUsageService.yaml, docs/architecture/nfr-baseline.md, docs/architecture/adr/0018-nfr-baseline.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-633 Health and meter conventions implementation Constants for the ready and live health tags, a helper through which a service declares its meter names under the rule that a name is lower case, dotted and starts with connectsoft. (under the Factory profile the connectsoft.factory.<area> prefixes model/services gives the metrics of the service, more than one per service allowed, and the template habit connectsoft.<service> for other generations), and the fixed names, units and tag sets of the drain, backlog and lease series the worker and aggregator templates publish exist in ConnectSoft.Extensions.Observability as the Factory convention. ConnectSoft.Extensions.Observability
AIFACTORY-TASK-1181 Conformance test package for health tags, declared meter names, instruments, series and own enrichers fixture A test package published beside the library holds the assertions a service calls from its architecture tests: the readiness and liveness endpoints report only checks with the ready and the live tag, and a check with neither is listed as informational; every meter created by an assembly of the solution has a declared name, and each of its instruments sits under a declared name, has a unit and was created through the instrument helper, while meters of libraries and of the runtime, such as ConnectSoft.Extensions.Telemetry, are not examined; a service with a background loop exposes the three series; and no type of the solution enriches a signal with a scope attribute; each failure names the offender. ConnectSoft.Extensions.Observability
AIFACTORY-TASK-1182 Convention page of the Observability library documentation A convention page of the documentation of the library names the two health tags and the informational checks, the rule for declared meter names with the connectsoft.factory.<area> prefixes of the Factory profile, the template habit that stays valid, the units, the scope of the assertion that leaves library and runtime meters out, and the drain, backlog and lease series with their tags, and names for each the constant and the assertion of the conformance test package that checks it; the Features page lists the page. ConnectSoft.Extensions.Observability
AIFACTORY-TASK-1183 Verify the conventions on a conforming and on five planted hosts verification Run the conformance test package against a conforming test host, which declares the two modelled names connectsoft.factory.runs and connectsoft.factory.attempts, carries a library meter and an informational check with neither tag, and against five hosts with a planted untagged check that the readiness probe reports, a planted undeclared meter, an instrument created outside the helper, a missing lease series and a planted enricher; the first passes and each of the five fails with its offender named, which proves AC1 to AC4 of AIFACTORY-US-258 (ADR-0018). ConnectSoft.Extensions.Observability

AIFACTORY-US-259: Observability libraries: activities and log records refuse prompt, completion and tool-output content by default and carry its reference instead

enabling · persona platform-admin As a platform admin, I want telemetry that cannot carry a prompt, a completion or a tool output unless a classification decision allows the field, so that no Factory service leaks customer content into traces and logs by writing one careless property.

ADR-0019 decision 3 forbids raw prompt, response and tool-output logging by default, and docs/architecture/data-governance.md states what telemetry carries instead: hashes, token counts, model and profile identifiers, policy receipts and sizes, while content lives only in the artifact store under the classification of the tenant. The Runbook page of the Telemetry library says that the redaction of the host applies to its log scope when the host enables it, so today the protection is opt-in and one service that forgets it leaks. This PBI turns the default around for the content of the Factory. The single registration installs a content guard that lives in ConnectSoft.Extensions.Telemetry. The guard knows three kinds of content field, prompt, completion and tool output, by the content attributes of the OpenTelemetry GenAI conventions that NFR-10 names and by the property names the Factory libraries use for them. When such a field is set as an activity tag, as an attribute of an activity event or as a property of a log record, the guard replaces the value by its reference: the hash and the size of the value and, when the caller supplies it, the artifact identifier. Nothing is thrown, so a careless property never fails a request, and every replacement is counted on a metric of the library without the value. The guard asks one decision interface whether a field may pass. In this increment no implementation of the interface allows anything, so the default is a refusal for every field of the three kinds; the Compliance library supplies the implementation that answers from the classification of a field in the next increment. The guard sees fields and attributes, not text a caller has already interpolated into a message; the convention page states that limit.

Acceptance criteria

AC1 Given a host with the single registration and no allow decision registered, when a prompt is placed in a property of a log record, then the exported record carries the hash and the size of the prompt under that property and not its text, and the replacement counter of the library grows by one without the value (ADR-0019 decision 3).
AC2 Given the same host, when a completion is set as an activity tag and a tool output as an attribute of an activity event, then the exported activity carries their references and not their values, the artifact identifier appears in the reference when the caller supplied it, and no exception leaves the guard (ADR-0019 decision 3, docs/architecture/data-governance.md).
AC3 Given a registered implementation of the decision interface that allows one named field, when that field and another content field are written, then the allowed field passes unchanged and the other is replaced by its reference; given no implementation is registered, then no field of the three kinds passes, which is the default ADR-0019 decision 3 requires.
Traces: adrs ADR-0019
Relates: nfrs NFR-10
Depends on AIFACTORY-US-257
Sources model/components.yaml, docs/architecture/adr/0019-data-governance.md, docs/architecture/data-governance.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1184 Content field kinds, the reference shape and the allow decision interface contract The Telemetry library defines the three content field kinds with the attribute and property names that identify them, the reference that replaces a value (hash, size and an optional artifact identifier) and one decision interface with the field name and kind as its input; no implementation of the interface ships in the library. ConnectSoft.Extensions.Telemetry
AIFACTORY-TASK-634 No prompt, completion or tool output in telemetry by default implementation Activity and log enrichment replace prompt, completion and tool-output fields by their reference unless a registered decision allows the field (ADR-0019); the guard is installed by the single registration, throws nothing and counts every replacement on a metric of the library, with a test that a prompt placed in a log property is replaced by its reference. ConnectSoft.Extensions.Telemetry
AIFACTORY-TASK-1185 Planted content tests over log properties, activity tags and activity events fixture A test fixture writes a planted prompt, completion and tool output through a log property, an activity tag and an activity event, with and without a registered allow decision, and asserts on the exported signals that no planted text appears where it was not allowed. ConnectSoft.Extensions.Telemetry
AIFACTORY-TASK-1186 Verify that no planted content reaches an exported signal verification Run dotnet test -c Release --no-build on the Telemetry solution; the planted content tests pass and a search of every exported signal of the suite finds no planted text outside the allowed field, which proves AC1 to AC3 of AIFACTORY-US-259 (ADR-0019). ConnectSoft.Extensions.Telemetry

AIFACTORY-US-260: Observability libraries: the Telemetry, Observability and conformance test packages are built, tested and published to the ConnectSoft feed with the versions the base template pins

evidence · persona platform-admin As a platform admin, I want the packages with the Factory conventions on the feed under versions a consumer can pin, so that the Factory profile of the base template wires its telemetry through a published registration and not through a local build.

This PBI is the publication proof of the feature. The epic is done only when each library publishes before the Factory code that consumes it is built (model/backlog/epics.yaml), and the Factory profile of the base template pins the single registration in the same increment. The Runbook page of the Telemetry library states that build, test, pack and publish run in azure-pipelines.yml in the pattern of the other ConnectSoft.Extensions.* repositories. The feed is the ConnectSoft feed, the Azure Artifacts feed the ConnectSoft libraries already publish to; the amendment of ADR-0028 on the Factory profile switch names that feed as the one the Factory publishes to and restores from. The pipelines publish in dependency order: the Telemetry package first, then the Observability package that references it, then the conformance test package. The abstractions package with the scope accessor is restored from the feed at the version the feature component-extensions-ai published, never from a project reference. A stage publishes only after the tests of its solution pass and refuses a version that is already on the feed. A probe then proves the result from the side of a consumer: a clean host that takes every ConnectSoft package from the feed and holds no project reference restores the published versions, makes the one call of the registration, establishes a scope and exports an activity and a log record with the five attributes, and a planted prompt in a log property leaves the host as a reference. The published versions are recorded on the Runbook pages of the two libraries, where the base template reads its pin. This is an evidence PBI (D113): a library feature has no scenario, so the probe names what it proves through its ADRs, the requirement on release gates and its sources.

Acceptance criteria

AC1 Given the pipelines of the two library repositories after the work of the feature, when they run, then the Telemetry package, the Observability package and the conformance test package are built, tested, packed and pushed to the ConnectSoft feed in that order, each stage publishes only after the tests of its solution pass, and the published versions are recorded on the Runbook pages of the libraries (FR-11, ADR-0028, model/backlog/epics.yaml).
AC2 Given a clean probe host that restores every ConnectSoft package from the feed and holds no project reference, when it makes the one call of the registration, establishes a scope and writes an activity and a log record, then both carry tenant, project, run, step and attempt, and a planted prompt in a log property is exported as its reference (ADR-0014 decision 1, ADR-0019 decision 3).
AC3 Given a failing test in a library solution or a version that is already on the feed, when the pipeline reaches the publication stage, then the stage is refused with the reason and the downstream package is not published on top of it; a run with a planted failing test proves the refusal (FR-11, docs/architecture/ecosystem-composition.md).
Traces: adrs ADR-0014, ADR-0019, ADR-0028
Traces: requirements FR-11
Depends on AIFACTORY-US-257, AIFACTORY-US-258, AIFACTORY-US-259, feature:component-extensions-ai
Sources model/components.yaml, model/backlog/epics.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/catalogs/libraries.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1187 Publication order and version guard in the Observability pipeline operations The pipeline of ConnectSoft.Extensions.Observability names the pipeline of the Telemetry library as its upstream pipeline resource, restores the Telemetry and abstractions packages from the ConnectSoft feed, publishes the library and the conformance test package after the tests of its solution pass, and refuses a version that is already on the feed with the reason. ConnectSoft.Extensions.Observability
AIFACTORY-TASK-1286 Version guard in the Telemetry pipeline operations The pipeline of ConnectSoft.Extensions.Telemetry restores the abstractions package from the ConnectSoft feed, publishes the Telemetry package only after the tests of its solution pass and refuses a version that is already on the feed with the reason, so that the Observability pipeline downstream never publishes on top of a Telemetry version that is not on the feed. ConnectSoft.Extensions.Telemetry
AIFACTORY-TASK-1188 Feed probe host for the published observability packages fixture A probe project that restores every ConnectSoft package from the feed and holds no project reference makes the one call of the registration, establishes a scope and exports an activity and a log record to an in-memory exporter, with a planted prompt in a log property; the probe runs as the last stage of the Observability pipeline. ConnectSoft.Extensions.Observability
AIFACTORY-TASK-1189 Published versions recorded on the Runbook page of the Observability library documentation The Runbook page of the Observability library names the version its package published, the version of the conformance test package and the versions of the Telemetry and abstractions packages it pins. ConnectSoft.Extensions.Observability
AIFACTORY-TASK-1287 Published version recorded on the Runbook page of the Telemetry library documentation The Runbook page of the Telemetry library names the version its package published and the version of the abstractions package it pins. ConnectSoft.Extensions.Telemetry
AIFACTORY-TASK-1190 Verify the published packages by the probe and by a planted failing run verification One run of the Telemetry pipeline followed by one run of the Observability pipeline publishes the three packages and the probe of the Observability pipeline passes; one run with a planted failing test in the Telemetry solution stops before publication and the Observability pipeline publishes nothing on top of it; both runs prove AC1 to AC3 of AIFACTORY-US-260 (FR-11, ADR-0028). ConnectSoft.Extensions.Observability

AIFACTORY-US-115: Observability libraries: the Factory telemetry conventions as one registration is delivered and proven by its consumers

enabling · persona platform-admin As a platform admin, I want Observability libraries to carry the Factory telemetry conventions as one registration, so that it serves OpenTelemetry, health, metrics without later rework.

This is the integration PBI of the feature. With the enrichment registration, the health and meter conventions with their conformance test package, the content guard and the publication proof of the earlier PBIs, the platform admin holds one answer to how a Factory service emits telemetry: it makes one call of the registration of the pinned ConnectSoft.Extensions.Observability package, creates its instruments through the instrument helper and references the conformance test package from its architecture tests. Every activity and log record then carries the tenant, project, run, step and attempt attributes under the connectsoft.factory. names of docs/planes/trust-operations/observability/observability.md from the scope accessor of the abstractions package, and the agent attribute inside an agent host; every instrument created through the helper carries the tags tenant and project; the workflow stays a dimension name and is no scope attribute; the health tags and the declared meter names follow one convention; and a prompt, a completion or a tool output leaves the process only as a reference. A service that writes its own enricher or creates a meter it did not declare is refused by its own architecture tests and not by a reviewer. The implementation lives in the tasks of the earlier PBIs; this PBI keeps the migrated verification of the feature and the pages a consumer reads. The feature is done when the three packages are on the ConnectSoft feed with the versions the Runbook pages name and the probe host proves them from the feed, which is what the Factory profile of the base template pins in the same increment.

Acceptance criteria

AC1 Given the two library repositories with the work of this feature, when their pipelines run, then the packages build, their tests pass and they publish to the ConnectSoft feed with the versions the consuming repositories pin (ADR-0018, model/components.yaml).
AC2 Given the work of AIFACTORY-TASK-632 (factory enrichment of traces, logs and metrics) is done, then one registration adds the tenant, project, run, step and attempt attributes to activities and log records from the scope accessor under the names docs/planes/trust-operations/observability/observability.md lists, adds the agent attribute while an agent host supplies its trace context, and tags the instruments created through the helper with tenant and project; the workflow of the migrated text is a metric dimension name only; the first five attribute names map to the envelope fields of the contracts package, and the conformance test fails a service that writes its own enricher (ADR-0014 decision 1).
AC3 Given the work of AIFACTORY-TASK-633 (health and meter conventions) is done, then the ready and live health tags, the meter names a service declares under connectsoft., which are the connectsoft.factory.<area> prefixes of model/services under the Factory profile, and the drain, backlog and lease series are documented as the Factory convention and checked by the conformance test package a service references (ADR-0018, docs/architecture/nfr-baseline.md).
AC4 Given the work of AIFACTORY-TASK-634 (no prompt, completion or tool output in telemetry by default) is done, then activity and log enrichment replace prompt, completion and tool-output fields by their reference unless a registered decision allows the field, with a test that a prompt placed in a log property is replaced by its reference (ADR-0019 decision 3).
Traces: adrs ADR-0014, ADR-0018, ADR-0019
Depends on AIFACTORY-US-257, AIFACTORY-US-258, AIFACTORY-US-259, AIFACTORY-US-260
Sources model/components.yaml, docs/architecture/adr/0019-data-governance.md, docs/architecture/adr/0018-nfr-baseline.md, docs/planes/trust-operations/observability/observability.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1191 Features and Getting Started pages of the Observability library describe the Factory conventions documentation The Features and Getting Started pages of the Observability library describe the single registration, the six scope attributes, the conventions with their conformance test package and where the content guard is documented, so that a consumer reads one page of the library and no source. ConnectSoft.Extensions.Observability
AIFACTORY-TASK-1288 Features page of the Telemetry library describes the enrichers, the instrument helper and the content guard documentation The Features page of the Telemetry library describes the activity and log enrichers, the scope tag provider with the metric tag allowlist, the instrument helper, the trace context method for the agent attribute and the content guard with its limit. ConnectSoft.Extensions.Telemetry
AIFACTORY-TASK-686 Verify observability-factory-conventions-delivered by running the declared command verification Run dotnet build -c Release and dotnet test -c Release --no-build on the solution of ConnectSoft.Extensions.Observability and the probe host of AIFACTORY-TASK-1188 against the published versions; they pass and prove AC1 to AC4 of AIFACTORY-US-115 from the side of the Observability library and of a consumer. ConnectSoft.Extensions.Observability
AIFACTORY-TASK-1290 Verify the Telemetry solution for the delivered conventions verification Run dotnet build -c Release and dotnet test -c Release --no-build on the solution of ConnectSoft.Extensions.Telemetry; they pass and prove the enrichment of AC2 and the content guard of AC4 of AIFACTORY-US-115 in the repository that holds them. ConnectSoft.Extensions.Telemetry