Guides
Building blocks.
Five patterns behind every use case.
Each pattern below is complete and ready to run. Combine them to build any of the use cases, or something only your product needs.
Headline numbers, with the trend
Name up to five counts and get them all in one call. include_previous adds the period just before, so every number arrives with its comparison. This is the opening line of the weekly report and the tiles in the customer view.
headline.py
from datetime import datetime, timedelta, timezonefrom ollive import Measure, MetricSpec, Ollive client = Ollive()now = datetime.now(timezone.utc) home = client.metrics.query( metrics=[ MetricSpec(name="runs", measure=Measure.RUNS), MetricSpec(name="findings", measure=Measure.FINDINGS), ], start=now - timedelta(days=30), end=now, include_previous=True,) runs = home.total["runs"].checked_run_countfindings = home.total["findings"].finding_countchange = findings - home.previous["findings"].finding_count print(f"{runs:,} runs checked")print(f"{findings} findings ({change:+d} on the 30 days before)")Where the risk sits
Add group_by to split every metric by rule set, rule, agent or severity. Groups come back ranked by your first metric, ready for a bar list like the weekly report’s.
breakdown.py
from ollive import MetricGroupBy by_rule_set = client.metrics.query( metrics=[ MetricSpec(name="findings", measure=Measure.FINDINGS), MetricSpec(name="runs", measure=Measure.RUNS), ], group_by=MetricGroupBy.RULE_SET_ID, start=now - timedelta(days=30), end=now,) for group in by_rule_set.groups: # most findings first findings = group.values["findings"].finding_count runs = group.values["runs"].checked_run_count print(f"{group.label}: {findings} findings across {runs:,} runs")A trend over time
Turn on timeseries, pick a bucket width, and every point comes back, quiet days included as zeros. Give each metric its own filters to draw several lines from one call, like the weekly report’s eight-week trend.
chart.py
from ollive import Severity daily = client.metrics.query( metrics=[ MetricSpec(name="findings", measure=Measure.FINDINGS), MetricSpec(name="critical", measure=Measure.FINDINGS, severities=[Severity.CRITICAL]), ], start=now - timedelta(days=30), end=now, timeseries=True, resolution_seconds=86400, # one point a day) points = [ (point.at.date(), point.values["findings"].finding_count, point.values["critical"].finding_count) for point in daily.series]The findings that matter most
Each finding is one rule an agent didn’t meet, with its severity, its rule set and how many conversations it covers. Filter by severity to lead with what matters, as the weekly report’s “Look at first” and the on-call alert do.
findings_table.py
findings = client.findings.list( severities=[Severity.CRITICAL, Severity.HIGH], start=now - timedelta(days=30), end=now,) for finding in findings: print( finding.severity, finding.rule.title or finding.rule.id, finding.rule_set_name, finding.in_time_range.run_count, finding.last_seen_at, )A finding’s first_seen_at and last_seen_at cover its whole history, while in_time_range counts the period you asked about. That’s how the alert tells a new finding from an ongoing one.
One agent, or one team
Pass agent_id to any of these calls to scope it to one agent. Run it for each agent a team owns and you have the team scorecard, or for the agents that serve one customer and you have their compliance view.
agent_page.py
agent = client.agents.get(agent_id) agent_home = client.metrics.query( metrics=[MetricSpec(name="findings", measure=Measure.FINDINGS)], agent_id=agent.id, include_previous=True,)agent_findings = client.findings.list(agent_id=agent.id)