Input format: telemetry mappings
Run the commands below from the installation directory. See Run operator commands for how ./lens reaches the running installation and copies files into it.
Five kinds, one shape: a source speaking its real vendor APIAPIApplication programming interface: a defined way for one program to request data or actions from another. or export format, a customer-authored mapping, and a shipped acquirerAcquirerA program that reads a customer's operational records, calculates quantities from them and records the results in NovusLens.. Anything unmapped is reported, never guessed. A simulated source declares itself and the label propagates to every score it produces.
From the installation directory:
./lens connectors acquire --org harbour --kind prometheus --url https://prom.example --mapping metrics.jsonOn success the command prints a summary of what it wrote and exits 0. The feed then needs the correction command (./lens connectors correct --org <org>) to turn it into commits; after that, the map shows the result on the projectionProjectionThe regular pass that brings the read model up to date with the canonical log. It runs every 30 seconds by default. service’s next pass (about 30 s by default). A refusal names what was wrong.
--kind is servicenow, jira, prometheus, github, composite or network-flow, and pagerduty inside a composite. A bearer tokenBearer tokenA secret value sent with a request to prove that the caller holds it. Anyone who obtains it can use it, so it must be protected. goes in --token.
What a mapping holds. Two joins, both the customer’s. cells is the identity joinSealed identity joinStored links between employee fingerprints and teams or services. The fingerprints replace readable employee identifiers. Product pages do not show the links for individual people.: which twinTwinNovusLens’s model of one organisation, built from records about its teams, services and how they rely on one another. It is only as current as those records. cellCellA box on the map that stands for a team, service, supplier or AI agent. It is a unit you can inspect, not necessarily a department or a person. corresponds to which job, repo or service in the source. axes is the calibrationCalibrationThe customer's own rule that turns raw figures, such as a gauge, a workflow history or an incident log, into a C/A/R score. A score moves when the calibration moves, and the change is recorded.: which exported series or computed quantity stands for each of Complexity, Agility and RecoverabilityRecoverabilityThe R in C/A/R: how well a team or service restores acceptable service after a failure. Recovery times and tested alternatives can supply evidence., and how raw quantities scale to a 0 to 100 score, as a base plus linear terms, clamped and rounded. A cell missing any calibrated input is refused whole, never padded, unless partial_axes is true, in which case the axes that can be scored are and the rest stay blank.
Tickets: servicenow, jira
Ticket queues become per-capability lead timesLead timeThe elapsed time between starting a request or handoff and completing it.. The mapping joins the source’s assignment groups to the twin’s capabilities.
{"groups": {"Customs Service Desk": {"capability": "declaration-filing"},
"Warehouse Ops": {"capability": "stock-movements"}}}Metrics: prometheus
cells joins each cell to the job label its exporters stamp. axes calibrates over exported series.
{"cells": {"customs": {"job": "customs-stack"}, "warehousing": {"job": "wms"}},
"axes": {"complexity": {"base": 0, "terms": [{"series": "estate_systems_total", "per_unit": 1.0}]},
"agility": {"base": 100, "terms": [{"series": "change_lead_time_days", "per_unit": -8.0}, {"series": "change_failure_rate_pct", "per_unit": -0.5}]},
"recoverability": {"base": 100, "terms": [{"series": "incident_recovery_hours", "per_unit": -5.0}]}}}Continuous integration: github
cells joins each cell to the repository whose pipelines deliver it. axes calibrates over quantities the acquirer computes from the raw workflow runs: ci_pipelines_total, ci_change_lead_days, ci_change_failure_rate_pct, ci_recovery_hours. Recovery is measured from a failed run to the next successful run of the same workflow on the same branch; a success elsewhere closes nothing, and a failure with no such success is counted as unrecovered. The failure rate covers every completed run retrieved, every workflow and branch. Listings are read page by page, and a repository or service whose listing could not be completed is refused with the counts rather than scored over a partial page.
{"cells": {"customs": {"repo": "harbour/customs-filing"}},
"axes": {"complexity": {"base": 0, "terms": [{"quantity": "ci_pipelines_total", "per_unit": 4.5}]},
"agility": {"base": 100, "terms": [{"quantity": "ci_change_lead_days", "per_unit": -8.0}, {"quantity": "ci_change_failure_rate_pct", "per_unit": -0.5}]},
"recoverability": {"base": 100, "terms": [{"quantity": "ci_recovery_hours", "per_unit": -5.0}]}}}Composed: several sources, one cell
When no single source measures every axis, compose. Each cell names its identity in each source, and each axis draws from the source that actually measures it. Incidents come from PagerDuty by service, as pd_mttr_hours.
From the installation directory:
./lens connectors acquire --org harbour --kind composite --source prometheus=https://prom.example --source pagerduty=https://api.pagerduty.com --mapping composed.jsonOn success the command prints a summary of what it wrote and exits 0. The feed then needs the correction command (./lens connectors correct --org <org>) to turn it into commits; after that, the map shows the result on the projection service’s next pass (about 30 s by default). A refusal names what was wrong.
{"cells": {"warehousing": {"job": "wms", "service": "wms-oncall"}},
"axes": {"complexity": {"base": 0, "terms": [{"series": "estate_systems_total", "per_unit": 1.0}]},
"agility": {"base": 100, "terms": [{"series": "change_lead_time_days", "per_unit": -8.0}]},
"recoverability": {"base": 100, "terms": [{"quantity": "pd_mttr_hours", "per_unit": -5.0}]}}}Partial calibration. Add "partial_axes": true to score the axes the mapping calibrates and leave the others blank, stated as such. Without it, a mapping that does not calibrate all three is refused before anything is acquired.
Every score lands at measured, labelled with its source and, where the source declared itself simulated, with that word.
What repeated acquisition does
| Situation | What happens |
|---|---|
| Stable identity | For metrics, CIContinuous integrationAutomated checks run when code changes, usually including building the code and running tests., incidents and composed sources: the cell, the axis and the source. For tickets: the capability. |
| The same pull twice | The feed entry is overwritten with a newer timestamp; after the next correction pass the observation is updated in place. |
| A changed reading | The newer observation replaces the older one. |
| A feed that stops | Entries older than three refresh intervals are ignored. An observation already on the map expires 30 days after it was observed and drops out of reads. |
| A cell in the mapping whose series is missing | Refused whole and listed as unmeasured, unless the mapping sets partial axes. |
| A job, repository or service present at the source but not mapped | Reported as unmapped; nothing is written. |
| A listing the source could not complete | Refused with the counts; a partial page is never scored. |
| Two sources for one cell | Each axis remembers its source. |
| A wrong reading | No correction route short of purging its evidence artifact, which drops the observation and opens a findingFindingA difference in the records that needs a decision. It includes its sources and can describe a slow handoff, disputed fact or missing owner.. |
| When visible | Not after the projection pass alone. An acquired feed reaches the map only after the correction command (./lens connectors correct --org <org>) turns it into commits; run it after each acquisition, or on the cadence the operations manual describes. |
Network flows: network-flow
A flow-log export, not an API: Cilium Hubble JSONJSONJavaScript Object Notation: a text format for data, using named fields, lists and values. Configuration files and service messages use it. (hubble observe -o json, --format hubble) or AWSAWSAmazon Web Services: a cloud platform whose account and resource exports NovusLens can read. VPCVPCVirtual private cloud: a private network defined inside a cloud provider's infrastructure. Flow Logs in the version 2 default format (--format vpc-flow-v2), passed with --flow-log (repeatable). The mapping joins each cell to the workloads that send for it, and declares the cell’s egressEgressTraffic leaving a system or network for another destination.. A Hubble selector names a namespaceNamespaceA naming area that keeps one set of records apart from another. NovusLens uses the conway/ prefix so its keys do not occupy Mycelium's reserved names. and labels; a VPC selector names source address ranges or network interfaces. A workload matching no cell, or more than one, is reported and not attributed. The declared egress lists destinations as host:port or an address, with a trailing * for a prefix, and says whether the list is complete. destinations gives your own names to addresses.
{"cells": {"eval-agents": {
"hubble": {"namespace": "eval-fleet", "labels": ["k8s:app=eval-agent"]},
"vpc": {"addresses": ["10.42.1.0/24"]},
"declared_egress": {"allowed": ["gateway.node-gateway.svc.cluster.local:8443"],
"excluded": [], "complete": true,
"source": "confined-fleet profile"}}},
"destinations": {"10.42.0.10": "gateway.node-gateway.svc.cluster.local"}}The result is the network’s own account of each cell’s egress, and two findings. See Network egress.