#! /usr/bin/python3.6
#
# Copyright (c) 2022-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at:
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import sys

if sys.version_info < (3, 8):
    sys.stderr.write(
        "ERROR: ovs-watch requires Python 3.8 or later.\n"
        "Current version: Python %d.%d.%d\n"
        "This feature is not supported on operating systems with older "
        "Python versions.\n"
        % (
            sys.version_info.major,
            sys.version_info.minor,
            sys.version_info.micro,
        )
    )
    sys.exit(1)

import argparse
import configparser
import enum
import math
import operator
import os
import re
import select
import shutil
import signal
from collections import deque
from copy import deepcopy
from dataclasses import dataclass, field, replace
from typing import (
    Callable,
    Deque,
    Dict,
    List,
    Optional,
    Sequence,
    TextIO,
    Tuple,
    Union,
)

try:
    from ovs.metrics import MetricsDB, MetricsPage, MetricsReadError
except ModuleNotFoundError:
    print(
        u"ERROR: Missing dependencies.\n"
        u"Please install the Open vSwitch python libraries: "
        u"python3-doca-openvswitch (version 3.6.0038).\n"
        u"Alternatively, install them from source: "
        u"( cd ovs/python ; python3 setup.py install ).\n"
        u"Alternatively, check that your PYTHONPATH is "
        u"pointing to the correct location."
    )
    sys.exit(1)

try:
    import plotext as plt
    HAVE_PLOTEXT = True
    PLOTEXT_IMPORT_ERROR: Optional[Exception] = None
except Exception as e:
    plt = None
    HAVE_PLOTEXT = False
    PLOTEXT_IMPORT_ERROR = (
        None if isinstance(e, ModuleNotFoundError) and e.name == 'plotext'
        else e
    )


# Minimum width of a rendered column, in characters.
MIN_COLUMN_WIDTH = 6
# Minimum width of a histogram column's "mean+-stdev" cell.
HIST_CELL_WIDTH = 16
# Cap on the points synthesised from bucket counts to feed plt.hist; bounds
# the per-frame cost while preserving the distribution's shape.
HIST_MAX_SAMPLES = 4000
# Number of samples kept per column for the graphical display.
GRAPH_HISTORY = 300
# Narrowest terminal that still yields a legible graph.  Below this the
# graphical view falls back to text: autowrap is disabled while a graph is
# shown, so a frame wider than the terminal would clip instead of wrapping.
GRAPH_MIN_WIDTH = 40
# plotext markers for the per-axis default plot styles: the left axis draws
# fine braille curves, the right axis solid lines, so overlaid series stay
# visually distinct.
MARKER_BRAILLE = "braille"
MARKER_LINE = "hd"
DEFAULT_MARKER = {"left": MARKER_BRAILLE, "right": MARKER_LINE}
# Metric name prefixes, to keep the column definitions readable.
DP = "ovs_vswitchd_datapath_"
DPIF = "ovs_vswitchd_dpif_"
OFPROTO = "ovs_vswitchd_"
MEM = "ovs_vswitchd_memory_"
POLL = "ovs_vswitchd_poll_threads_"


def human_convert(value: float, power: int = 1000) -> Tuple[float, str]:
    """Scale 'value' down by 'power' (1000 or 1024) and return the scaled
    value together with its SI (or binary) order suffix."""
    n = 0
    labels = ['', 'K', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y', 'R', 'Q']
    if power == 1024:
        labels = [x + 'i' for x in labels]
        labels[0] = ''
    if power not in (1000, 1024):
        raise ValueError("Unsupported power value for human conversion.")
    while abs(value) > power and n in range(len(labels) - 1):
        value /= power
        n += 1
    return value, labels[n]


class TickFormat(enum.IntFlag):
    """How a numeric value is rendered on an axis (or in a column).

    The flags combine.  INT and FLOAT select the precision of the unscaled
    value (no decimals vs two).  SCALED instead divides the value by its
    series base and appends an order suffix, so FLOAT | SCALED keeps decimals
    near zero but drops them once a suffix appears.  SCIENTIFIC overrides the
    rest with mantissa/exponent notation.

    Whether the base is a power of ten or two is intrinsic to the series unit
    (e.g. bytes), carried separately as 'power' (1000 or 1024)."""

    INT = 1
    FLOAT = 2
    SCALED = 4
    SCIENTIFIC = 8


TICK_FORMAT_INT = TickFormat.INT
TICK_FORMAT_FLOAT = TickFormat.FLOAT
TICK_FORMAT_SCALED = TickFormat.SCALED
TICK_FORMAT_SCIENTIFIC = TickFormat.SCIENTIFIC


def format_tick(value: float, fmt: TickFormat, power: int = 1000) -> str:
    """Format 'value' per 'fmt'.  'power' (1000 for SI, 1024 for binary units)
    picks the suffix family used when SCALED divides the value down."""
    if fmt & TickFormat.SCIENTIFIC:
        return '{:.1e}'.format(value)
    if fmt & TickFormat.SCALED:
        value, order = human_convert(value, power)
        if order:
            return '{:.0f}{}'.format(value, order)
    if fmt & TickFormat.FLOAT:
        return '{:.2f}'.format(value)
    return '{:.0f}'.format(value)


def format_time_tick(value: float) -> str:
    """Format an x-axis time tick (seconds) as compactly as possible: keep one
    decimal ('225.2') but drop a zero fraction ('1.0' becomes '1')."""
    text = '{:.1f}'.format(value)
    if text.endswith('.0'):
        text = text[:-2]
    return text


def axis_ticks(lo: float, hi: float, scale: str = "linear",
               count: int = 5, base: int = 10) -> List[float]:
    """Return tick positions spanning ['lo', 'hi'].

    A 'log' axis gets one tick per power of 'base' (10 for SI, 2 for binary
    units), clamping non-positive bounds so the logarithm stays defined.  A
    linear axis gets up to 'count' evenly spaced ticks, anchored on zero when
    zero lies in range so the baseline is labeled; a single requested tick is
    zero (when in range) or else the midpoint."""
    if scale == "log":
        lo = lo if lo > 0 else 1.0
        hi = hi if hi > lo else lo * base
        first = int(math.floor(math.log(lo, base)))
        last = int(math.ceil(math.log(hi, base)))
        return [float(base) ** exp for exp in range(first, last + 1)]
    if hi <= lo:
        hi = lo + 1.0
    if count <= 1:
        return [0.0] if lo <= 0 <= hi else [(lo + hi) / 2.0]
    step = (hi - lo) / (count - 1)
    if lo <= 0 <= hi:
        first = int(math.floor(lo / step))
        last = int(math.ceil(hi / step))
        return [k * step for k in range(first, last + 1)
                if lo <= k * step <= hi]
    return [lo + step * i for i in range(count)]


# An operator folds a list of source values into a single column value.
Operator = Callable[[Sequence[float]], float]


def _fold(values: Sequence[float], op: Callable[[float, float], float]
          ) -> float:
    """Reduce 'values' left to right using the binary operator 'op'."""
    result = values[0]
    for value in values[1:]:
        result = op(result, value)
    return result


OPERATORS: Dict[str, Operator] = {
    "sub": lambda vs: _fold(vs, operator.sub),
    "add": lambda vs: _fold(vs, operator.add),
    "sum": lambda vs: float(sum(vs)),
    "mul": lambda vs: _fold(vs, operator.mul),
    "min": lambda vs: float(min(vs)),
    "max": lambda vs: float(max(vs)),
    "first": lambda vs: vs[0],
    "last": lambda vs: vs[-1],
}


@dataclass
class SeriesRef:
    """A reference to a single metric series: its 'name' and an optional label
    set selecting one series among the metric's labeled variants."""

    name: str
    labels: Optional[Dict[str, str]] = None


@dataclass
class TimeSeries:
    """A displayed column.

    A column watches one or more metric series, folds them into a single value
    with 'operator', and optionally reports the time-derivative of that value
    rather than the value itself."""

    name: str
    unit: str
    sources: List[SeriesRef]
    operator: Operator = OPERATORS["sub"]
    derivative: bool = False
    precision: int = 0
    power: int = 1000
    tick_format: Optional[TickFormat] = None
    page: MetricsPage = MetricsPage.DEFAULT
    width: int = field(default=0, init=False)
    raw: float = field(default=0.0, init=False)
    value: float = field(default=0.0, init=False)
    update_count: int = field(default=0, init=False)
    disabled: bool = field(default=False, init=False)

    def __post_init__(self) -> None:
        """Size the column and default its tick format from its kind: rates
        carry fractional detail (FLOAT), discrete values do not (INT)."""
        self.width = max(len(self.name), len(self.unit_text()),
                         MIN_COLUMN_WIDTH)
        if self.tick_format is None:
            self.tick_format = (TICK_FORMAT_FLOAT if self.derivative
                                else TICK_FORMAT_INT)

    def unit_text(self) -> str:
        """Return the unit string, suffixed with '/s' for rates."""
        return self.unit + '/s' if self.derivative else self.unit

    def read_combined(self, db: MetricsDB) -> Optional[float]:
        """Read every source from 'db' and fold them into one value.

        Returns None and disables the column if any source is missing (e.g. a
        hardware-offload metric while offload is disabled)."""
        values: List[float] = []
        for ref in self.sources:
            value = db.get(ref.name, ref.labels)
            if value is None:
                self.disabled = True
                return None
            values.append(value)
        if not values:
            return None
        self.disabled = False
        return self.operator(values)

    def update(self, db: MetricsDB) -> None:
        """Read a new value from 'db', computing a per-second rate when this
        column is a time-derivative."""
        combined = self.read_combined(db)
        if combined is None:
            if self.derivative:
                self.raw = 0.0
                self.value = 0.0
                self.update_count = 0
            return
        if self.derivative:
            ms = db.ts_delta()
            if self.update_count > 0 and ms > 0:
                self.value = (combined - self.raw) * (1000.0 / ms)
            else:
                self.value = 0.0
            self.raw = combined
        else:
            self.value = combined
        self.update_count += 1

    def legend(self) -> str:
        """Return the column header cell."""
        return '{:>{w}}'.format(self.name, w=self.width)

    def unit_label(self) -> str:
        """Return the column unit cell, suffixed with '/s' for rates."""
        return '{:>{w}}'.format(self.unit_text(), w=self.width)

    def format_human(self) -> str:
        """Return the current value as a human-readable, right-aligned cell."""
        if self.disabled:
            return '{:>{w}}'.format('-', w=self.width)
        value, order = human_convert(self.value, self.power)
        if self.derivative or value != self.value:
            precision = 2
        else:
            precision = self.precision
        return '{0:.{1}f}{2}'.format(value, precision, order).rjust(self.width)

    def format_csv(self) -> str:
        """Return the current value as a fixed-precision cell for CSV."""
        precision = 2 if self.derivative else self.precision
        return '{0:{1}.{2}f}'.format(self.value, self.width, precision)


def _sum_last(metric) -> float:
    """Sum the most recent value of every label set of 'metric'."""
    return sum(samples[-1] for samples in metric.samples.values())


def read_histogram(db: MetricsDB, base: str
                   ) -> Optional[Tuple[List[float], List[float],
                                       float, float]]:
    """Aggregate the Prometheus histogram named 'base' over all its label
    sets (e.g. all revalidator threads), reading from 'db'.

    Returns '(edges, counts, total_sum, total_count)' where 'edges' are the
    bucket upper bounds in ascending order (the last being +Inf) and 'counts'
    the matching per-bucket (non-cumulative) totals, or None when the metric
    is absent."""
    metrics = getattr(db, 'metrics', None)
    if metrics is None:
        return None
    buckets = metrics.get(base + '_bucket')
    counts = metrics.get(base + '_count')
    if buckets is None or counts is None:
        return None
    cumulative: Dict[float, float] = {}
    for key, labels in buckets.labels.items():
        le = labels.get('le') if labels else None
        if le is None:
            continue
        edge = math.inf if le in ('+Inf', 'Inf') else float(le)
        cumulative[edge] = cumulative.get(edge, 0.0) + buckets.samples[key][-1]
    if not cumulative:
        return None
    edges = sorted(cumulative)
    per_bucket: List[float] = []
    prev = 0.0
    for edge in edges:
        per_bucket.append(max(0.0, cumulative[edge] - prev))
        prev = cumulative[edge]
    total_sum = _sum_last(metrics[base + '_sum']) \
        if (base + '_sum') in metrics else 0.0
    return edges, per_bucket, total_sum, _sum_last(counts)


def histogram_stdev(edges: List[float], counts: List[float],
                    mean: float) -> float:
    """Estimate the standard deviation of a bucketed distribution, taking each
    bucket's midpoint as the value of its samples (the +Inf bucket its lower
    bound), since only bucket counts are available, not the raw samples."""
    total = sum(counts)
    if total <= 0:
        return 0.0
    variance = 0.0
    lower = 0.0
    for edge, count in zip(edges, counts):
        rep = lower if math.isinf(edge) else (lower + edge) / 2.0
        variance += count * (rep - mean) ** 2
        if not math.isinf(edge):
            lower = edge
    return math.sqrt(variance / total)


def histogram_samples(edges: List[float], counts: List[float],
                      cap: int) -> List[float]:
    """Synthesise up to 'cap' values from per-bucket 'counts', placing each at
    its bucket midpoint, so plt.hist (which bins raw values) can redraw a
    distribution we only hold pre-bucketed.  Counts are scaled down to stay
    within 'cap', preserving the shape."""
    total = sum(counts)
    if total <= 0:
        return []
    scale = cap / total if total > cap else 1.0
    data: List[float] = []
    lower = 0.0
    for edge, count in zip(edges, counts):
        rep = lower if math.isinf(edge) else (lower + edge) / 2.0
        repeats = int(round(count * scale))
        if repeats:
            data.extend([rep] * repeats)
        if not math.isinf(edge):
            lower = edge
    return data


@dataclass
class Histogram:
    """A histogram column.

    It reports the mean (and a bucket-estimated standard deviation) of a
    Prometheus histogram 'metric', aggregated over all its label sets, and is
    drawn as its own plt.hist graph rather than as a time series."""

    name: str
    metric: str
    unit: str = ''
    page: MetricsPage = MetricsPage.DEFAULT
    derivative: bool = field(default=False, init=False)
    sources: List[SeriesRef] = field(default_factory=list, init=False)
    width: int = field(default=0, init=False)
    value: float = field(default=0.0, init=False)
    mean: float = field(default=0.0, init=False)
    stdev: float = field(default=0.0, init=False)
    count: float = field(default=0.0, init=False)
    edges: List[float] = field(default_factory=list, init=False)
    counts: List[float] = field(default_factory=list, init=False)
    disabled: bool = field(default=False, init=False)

    def __post_init__(self) -> None:
        self.sources = [SeriesRef(self.metric)]
        self.width = max(len(self.name), len(self.unit),
                         HIST_CELL_WIDTH, MIN_COLUMN_WIDTH)

    def unit_text(self) -> str:
        """Return the unit string (histograms are never rates)."""
        return self.unit

    def update(self, db: MetricsDB) -> None:
        """Read the latest buckets from 'db' and recompute mean and stdev."""
        result = read_histogram(db, self.metric)
        if result is None:
            self.disabled = True
            return
        self.disabled = False
        self.edges, self.counts, total_sum, self.count = result
        if self.count > 0:
            self.mean = total_sum / self.count
            self.stdev = histogram_stdev(self.edges, self.counts, self.mean)
        else:
            self.mean = 0.0
            self.stdev = 0.0
        self.value = self.mean

    def legend(self) -> str:
        """Return the column header cell."""
        return '{:>{w}}'.format(self.name, w=self.width)

    def unit_label(self) -> str:
        """Return the column unit cell."""
        return '{:>{w}}'.format(self.unit, w=self.width)

    def format_human(self) -> str:
        """Return the 'mean+-stdev' cell, or '-' when there are no samples."""
        if self.disabled or self.count <= 0:
            return '{:>{w}}'.format('-', w=self.width)
        cell = '{:.1f}+-{:.1f}'.format(self.mean, self.stdev)
        return cell.rjust(self.width)

    def format_csv(self) -> str:
        """Return the mean as a fixed-precision cell for CSV."""
        return '{0:{1}.2f}'.format(self.mean, self.width)


# A dashboard column is either a scalar time series or a histogram.
Column = Union[TimeSeries, Histogram]


class Direction(enum.Enum):
    """Plotting direction of a series on a graph axis."""

    UP = enum.auto()
    DOWN = enum.auto()


class StatFlags(enum.Flag):
    """Summary statistics annotated on a series in the graph legend.  MEAN is
    the arithmetic mean; EMA replaces it with an exponential moving average;
    SD adds the corresponding standard deviation (of the EMA when EMA is
    set)."""

    NONE = 0
    MEAN = enum.auto()
    SD = enum.auto()
    EMA = enum.auto()


DEFAULT_STATS = StatFlags.MEAN | StatFlags.SD


@dataclass(frozen=True)
class SeriesView:
    """Presentation of a named series on one graph axis.  'name' references a
    column; 'direction' defaults to UP (DOWN mirrors the series below the
    baseline, so opposing rates can share an axis); 'marker' overrides the
    axis default plot style when set.  Direction and marker belong to the view
    rather than the series, so the same column can appear differently across
    graphs.

    'stats' overrides, for this series only, the statistics its graph annotates
    in the legend, so different series on one graph can show different measures
    (e.g. an EMA for one, an arithmetic mean for another); it inherits the
    graph's 'stats' when left unset.  A set 'stats' selecting EMA makes its SD
    the EMA's own."""

    name: str
    direction: Direction = Direction.UP
    marker: Optional[str] = None
    stats: Optional[StatFlags] = None

    @property
    def sign(self) -> float:
        """Return the multiplier applied to the series' values: -1.0 for a
        DOWN view (mirrored below the baseline), 1.0 otherwise."""
        return -1.0 if self.direction is Direction.DOWN else 1.0


@dataclass
class GraphSpec:
    """A graph in the graphical display.

    'series' is the list of 'SeriesView' drawn on the left y-axis; a DOWN view
    is mirrored below the baseline so that, e.g., a Tx rate can be drawn
    against an Rx rate above it.  Series whose magnitude differs from the left
    axis (e.g. a rate plotted against a count) can be moved to a second
    right-hand y-axis via 'right_series'.

    'xscale', 'yscale' and 'right_yscale' select 'linear' or 'log' for each
    axis.

    'ysigned' / 'right_ysigned' keep the real sign on the axis' tick labels;
    by default a mirrored (DOWN) series is labeled with its absolute
    magnitude, since a series is a monotonic-counter derivative and only its
    plotting direction, not its value, is negative.

    Tick formatting and scaling base are derived from the plotted columns (an
    axis is SCALED by default); 'ytick_format' / 'right_ytick_format' override
    that derived 'TickFormat' for an axis when set.

    'stats' selects the summary statistics annotated on this graph's series in
    the legend (none by default); an individual 'SeriesView' may override it to
    show a different measure for that series.  'stats_window' bounds how many
    of the most recent samples those statistics consider, letting a graph
    emphasise recent events: it caps the arithmetic mean's window, or sets the
    EMA smoothing factor to 2/(N+1) so the EMA matches an N-sample average's
    centre of mass (as in lib/mov-avg.h)."""

    title: str
    series: List[SeriesView]
    stats: StatFlags = StatFlags.NONE
    stats_window: Optional[int] = None
    xscale: str = "linear"
    yscale: str = "linear"
    ytick_format: Optional[TickFormat] = None
    ysigned: bool = False
    right_series: List[SeriesView] = field(default_factory=list)
    right_yscale: str = "linear"
    right_ytick_format: Optional[TickFormat] = None
    right_ysigned: bool = False


@dataclass
class Dashboard:
    """A named selection of columns (and optional graphs) to display."""

    name: str
    title: str
    columns: List[str]
    description: str = ""
    aliases: List[str] = field(default_factory=list)
    graphs: List[GraphSpec] = field(default_factory=list)


def auto_graphs(columns: List[TimeSeries]) -> List[GraphSpec]:
    """Derive graphs for a dashboard that defines none, grouping columns that
    share a base unit onto one diagram.  When a group mixes rates with absolute
    values their scales differ, so rates take the left axis and values the
    right.

    Order follows first appearance; each series is drawn upward."""
    by_unit: Dict[str, List[TimeSeries]] = {}
    for col in columns:
        by_unit.setdefault(col.unit, []).append(col)
    graphs = []
    for unit, cols in by_unit.items():
        rates = [c.name for c in cols if c.derivative]
        values = [c.name for c in cols if not c.derivative]
        if rates and values:
            left, right = rates, values
        else:
            left, right = [c.name for c in cols], []
        graphs.append(GraphSpec(
            unit or "value",
            [SeriesView(name) for name in left],
            right_series=[SeriesView(name) for name in right]))
    return graphs


def _ts(name: str, unit: str, sources: Sequence[str], **kwargs) -> TimeSeries:
    """Build a TimeSeries from plain metric names, for the column registry."""
    refs = [SeriesRef(s) for s in sources]
    return TimeSeries(name=name, unit=unit, sources=refs, **kwargs)


def build_columns() -> Dict[str, TimeSeries]:
    """Return a fresh registry of all built-in columns, keyed by name."""
    columns = [
        # Packets.
        _ts('sw-rx-pkt', 'pkt',
            [DP + 'packets_total', DP + 'offloaded_packets_total']),
        _ts('sw-rx-pps', 'pkt',
            [DP + 'packets_total', DP + 'offloaded_packets_total'],
            derivative=True),
        _ts('sw-tx-pkt', 'pkt',
            [DP + 'tx_packets_total', DP + 'tx_offloaded_packets_total']),
        _ts('sw-tx-pps', 'pkt',
            [DP + 'tx_packets_total', DP + 'tx_offloaded_packets_total'],
            derivative=True),
        _ts('hw-rx-pkt', 'pkt', [DP + 'offloaded_packets_total']),
        _ts('hw-rx-pps', 'pkt', [DP + 'offloaded_packets_total'],
            derivative=True),
        _ts('hw-tx-pkt', 'pkt', [DP + 'tx_offloaded_packets_total']),
        _ts('hw-tx-pps', 'pkt', [DP + 'tx_offloaded_packets_total'],
            derivative=True),
        # Connections.
        _ts('sw-conns', 'conn', [DP + 'n_connections']),
        _ts('sw-cps', 'conn', [DP + 'n_connections'], derivative=True),
        _ts('hw-conns', 'conn', [DP + 'hw_offload_n_ct_bidir']),
        _ts('hw-cps', 'conn', [DP + 'hw_offload_n_ct_bidir'],
            derivative=True),
        # Connection create / delete rates (debug page).
        _ts('sw-conn-add-ops', 'op', [DP + 'conn_created'],
            derivative=True, page=MetricsPage.DEBUG),
        _ts('sw-conn-del-ops', 'op', [DP + 'conn_deleted'],
            derivative=True, page=MetricsPage.DEBUG),
        _ts('hw-conn-add-ops', 'op', [DP + 'conn_offload_add_processed'],
            derivative=True, page=MetricsPage.DEBUG),
        _ts('hw-conn-del-ops', 'op', [DP + 'conn_offload_del_processed'],
            derivative=True, page=MetricsPage.DEBUG),
        # Tracked connections per protocol.
        _ts('ct-tcp', 'conn', [DP + 'n_connections_tcp']),
        _ts('ct-udp', 'conn', [DP + 'n_connections_udp']),
        _ts('ct-icmp', 'conn', [DP + 'n_connections_icmp']),
        # Flows.
        _ts('sw-flows', 'flow',
            [DP + 'n_flows', DP + 'n_offloaded_flows']),
        _ts('hw-flows', 'flow', [DP + 'n_offloaded_flows']),
        # Offload insertion / backlog.
        _ts('hw-rules', 'rule', [DP + 'hw_offload_n_inserted']),
        _ts('hw-rps', 'rule', [DP + 'hw_offload_n_inserted'], derivative=True),
        _ts('offload-queue', 'req', [DP + 'hw_offload_n_enqueued']),
        # Datapath flow-table behavior.
        _ts('dp-hit-pps', 'pkt', [DP + 'hit_total'], derivative=True),
        _ts('dp-miss-pps', 'pkt', [DP + 'missed_total'], derivative=True),
        _ts('dp-lost-pps', 'pkt', [DP + 'lost_total'], derivative=True),
        _ts('dp-flows', 'flow', [DP + 'n_flows']),
        _ts('dp-masks', 'mask', [DP + 'n_masks']),
        _ts('mfc-hps', 'hit', [DP + 'cache_hit_total'],
            derivative=True),
        _ts('subtbl-lps', 'lkup', [DP + 'mask_hit_total'],
            derivative=True),
        # Upcall / revalidation.
        _ts('handlers', 'thr', [OFPROTO + 'handler_n_threads']),
        _ts('revalidators', 'thr', [OFPROTO + 'revalidator_n_threads']),
        _ts('flow-del-no-rev', 'flow',
            [OFPROTO + 'revalidator_flow_del_no_rev_total']),
        _ts('flow-put-ops', 'op', [DPIF + 'flow_put_total'],
            derivative=True, page=MetricsPage.DEBUG),
        _ts('flow-del-ops', 'op', [DPIF + 'flow_del_total'],
            derivative=True, page=MetricsPage.DEBUG),
        _ts('flow-get-ops', 'op', [DPIF + 'flow_get_total'],
            derivative=True, page=MetricsPage.DEBUG),
        # Per-PMD (poll thread) datapath statistics.
        _ts('pmd-rx-pps', 'pkt', [POLL + 'packets_total'], derivative=True),
        _ts('pmd-hit-pps', 'pkt', [POLL + 'hit_total'], derivative=True),
        _ts('pmd-miss-pps', 'pkt', [POLL + 'missed_total'], derivative=True),
        _ts('pmd-lost-pps', 'pkt', [POLL + 'lost_total'], derivative=True),
        _ts('pmd-recirc-pps', 'pkt', [POLL + 'recirculations_total'],
            derivative=True),
        _ts('pmd-lookups', 'lkup', [POLL + 'lookups_per_hit'], precision=2),
        _ts('pmd-batch', 'pkt', [POLL + 'packets_per_batch'], precision=2),
        _ts('pmd-cycles', 'cyc', [POLL + 'cycles_per_packet']),
        _ts('pmd-busy', '%', [POLL + 'busy_cycles'], precision=1),
        _ts('pmd-idle', '%', [POLL + 'idle_cycles'], precision=1),
        # Memory (not part of any built-in dashboard, but available).
        _ts('rss', 'byte', [MEM + 'rss'], power=1024),
        _ts('used-mem', 'byte', [MEM + 'in_use'], power=1024),
        _ts('frag', '', [MEM + 'frag_factor'], precision=2),
    ]
    return {col.name: col for col in columns}


def build_dashboards() -> Dict[str, Dashboard]:
    """Return a fresh registry of all built-in dashboards, keyed by name."""
    dashboards = [
        Dashboard(
            name='offloads',
            title='Offloads',
            description='Software and hardware packet, connection and flow '
                        'offload activity.',
            aliases=['of'],
            columns=[
                'sw-rx-pps', 'sw-tx-pps', 'hw-rx-pps', 'hw-tx-pps',
                'sw-conns', 'sw-cps', 'hw-conns', 'hw-cps',
                'sw-flows', 'hw-flows', 'hw-rules', 'offload-queue',
            ],
            graphs=[
                GraphSpec('packets',
                          [SeriesView('sw-rx-pps'),
                           SeriesView('sw-tx-pps', Direction.DOWN)],
                          right_series=[SeriesView('hw-rx-pps'),
                                        SeriesView('hw-tx-pps',
                                                   Direction.DOWN)],
                          stats=DEFAULT_STATS),
                GraphSpec('flows',
                          [SeriesView('sw-flows'), SeriesView('hw-flows')],
                          right_series=[SeriesView('offload-queue')]),
                GraphSpec('connections',
                          [SeriesView('sw-conns'), SeriesView('hw-conns')],
                          right_series=[SeriesView('sw-cps'),
                                        SeriesView('hw-cps')],
                          stats=DEFAULT_STATS),
            ],
        ),
        Dashboard(
            name='datapath',
            title='Datapath',
            description='Datapath behavior including revalidation, combining '
                        'flow-table, dpif and upcall signals.',
            aliases=['dp'],
            columns=[
                'dp-hit-pps', 'dp-miss-pps', 'dp-lost-pps',
                'dp-flows', 'dp-masks', 'mfc-hps', 'subtbl-lps',
                'handlers', 'revalidators', 'flow-put-ops', 'flow-del-ops',
                'flow-del-no-rev',
            ],
            graphs=[
                GraphSpec('Datapath hit/miss',
                          [SeriesView('dp-hit-pps'),
                           SeriesView('dp-miss-pps')],
                          right_series=[SeriesView('dp-flows'),
                                        SeriesView('dp-masks')]),
                GraphSpec('flow ops/s',
                          [SeriesView('flow-put-ops'),
                           SeriesView('flow-del-ops', Direction.DOWN),
                           SeriesView('flow-del-no-rev', Direction.DOWN)]),
            ],
        ),
        Dashboard(
            name='conntrack',
            title='Conntrack',
            description='Software connection tracking: counts, rates and '
                        'per-protocol breakdown.',
            aliases=['ct'],
            columns=[
                'sw-conns', 'sw-cps', 'sw-conn-add-ops', 'sw-conn-del-ops',
                'ct-tcp', 'ct-udp', 'ct-icmp',
            ],
            graphs=[
                GraphSpec('connections',
                          [SeriesView('sw-cps'),
                           SeriesView('sw-conn-add-ops'),
                           SeriesView('sw-conn-del-ops', Direction.DOWN)],
                          right_series=[SeriesView('sw-conns')],
                          stats=DEFAULT_STATS),
                GraphSpec('by protocol',
                          [SeriesView('ct-tcp'), SeriesView('ct-udp'),
                           SeriesView('ct-icmp')]),
            ],
        ),
        Dashboard(
            name='conntrack-offload',
            title='Conntrack offload',
            description='Software and hardware connection tracking counts and '
                        'insertion/deletion rates.',
            aliases=['cto'],
            columns=[
                'sw-conns', 'hw-conns', 'sw-cps', 'hw-cps',
                'sw-conn-add-ops', 'hw-conn-add-ops',
                'sw-conn-del-ops', 'hw-conn-del-ops',
            ],
            graphs=[
                GraphSpec('sw connections',
                          [SeriesView('sw-conns')],
                          right_series=[SeriesView('sw-conn-add-ops'),
                                        SeriesView('sw-conn-del-ops',
                                                   Direction.DOWN)],
                          stats=StatFlags.EMA | StatFlags.SD),
                GraphSpec('hw connections',
                          [SeriesView('hw-conns')],
                          right_series=[SeriesView('hw-conn-add-ops'),
                                        SeriesView('hw-conn-del-ops',
                                                   Direction.DOWN)],
                          stats=StatFlags.EMA | StatFlags.SD),
            ],
        ),
        Dashboard(
            name='polling',
            title='Polling',
            description='Per-PMD (poll thread) datapath packet rates, lookup '
                        'efficiency and CPU usage.',
            aliases=['pmd'],
            columns=[
                'pmd-rx-pps', 'pmd-hit-pps', 'pmd-miss-pps', 'pmd-lost-pps',
                'pmd-recirc-pps', 'pmd-lookups', 'pmd-batch', 'pmd-cycles',
                'pmd-busy', 'pmd-idle',
            ],
            graphs=[
                GraphSpec('pmd pkt/s',
                          [SeriesView('pmd-rx-pps')]),
                GraphSpec('hit / miss',
                          [SeriesView('pmd-hit-pps'),
                           SeriesView('pmd-miss-pps', Direction.DOWN)]),
                GraphSpec('cpu %',
                          [SeriesView('pmd-busy'),
                           SeriesView('pmd-idle', Direction.DOWN)],
                          stats=DEFAULT_STATS),
            ],
        ),
        Dashboard(
            name='legacy',
            title='Legacy',
            description='Previous ovs-metrics output for compatibility.',
            aliases=[],
            columns=[
                'sw-tx-pkt', 'sw-tx-pps', 'sw-conns', 'sw-cps',
                'hw-tx-pkt', 'hw-tx-pps', 'hw-conns', 'hw-cps',
                'offload-queue', 'hw-rules', 'hw-rps',
                'rss', 'used-mem', 'frag',
            ],
        ),
    ]
    return {dash.name: dash for dash in dashboards}


def parse_list(text: str) -> List[str]:
    """Split a comma or whitespace separated list, dropping empty items."""
    return [item for item in re.split(r'[,\s]+', text.strip()) if item]


def parse_labels(text: str) -> Optional[Dict[str, str]]:
    """Parse a '{k="v",...}' label expression into a dict, or None when the
    selector is empty.  A malformed selector raises ValueError instead of
    being parsed partially, so a typo cannot silently change the selection."""
    inner = text.strip()
    if inner.startswith('{') and inner.endswith('}'):
        inner = inner[1:-1]
    if not inner.strip():
        return None
    pair = r'\w+\s*=\s*"[^"]*"'
    if not re.fullmatch(r'\s*%s\s*(,\s*%s\s*)*,?\s*' % (pair, pair), inner):
        raise ValueError("Invalid label selector: '%s'" % text)
    labels: Dict[str, str] = {}
    for key, value in re.findall(r'(\w+)\s*=\s*"([^"]*)"', inner):
        if key in labels:
            raise ValueError("Duplicate label '%s' in selector: '%s'"
                             % (key, text))
        labels[key] = value
    return labels


def parse_sources(text: str) -> List[SeriesRef]:
    """Parse a comma- or whitespace-separated list of 'name' or 'name{labels}'
    source references.  Junk between references raises ValueError instead of
    being skipped, so a typo cannot silently change the series queried."""
    refs: List[SeriesRef] = []
    token = re.compile(r'(?P<name>[A-Za-z_:][\w:]*)(?P<labels>\{[^}]*\})?')
    leading = re.compile(r'[,\s]*')
    between = re.compile(r'[,\s]+')
    pos = leading.match(text).end()
    while pos < len(text):
        match = token.match(text, pos)
        if not match:
            raise ValueError("Invalid source reference in '%s'" % text)
        labels = match.group('labels')
        refs.append(SeriesRef(match.group('name'),
                              parse_labels(labels) if labels else None))
        pos = match.end()
        if pos < len(text):
            gap = between.match(text, pos)
            if not gap:
                raise ValueError("Invalid source reference in '%s'" % text)
            pos = gap.end()
    return refs


def parse_page(text: str) -> MetricsPage:
    """Parse a page expression such as 'default', 'debug' or
    'extended+debug'."""
    page = MetricsPage.DEFAULT
    for token in re.split(r'[+,\s]+', text.strip().lower()):
        if token in ('', 'default'):
            continue
        elif token == 'extended':
            page |= MetricsPage.EXTENDED
        elif token == 'debug':
            page |= MetricsPage.DEBUG
        else:
            raise ValueError("Unknown metrics page: '%s'" % token)
    return page


def parse_tick_format(text: str) -> Optional[TickFormat]:
    """Parse a tick-format expression such as 'float|scaled' into combined
    'TickFormat' flags, or None for the empty string (keep the default)."""
    fmt: Optional[TickFormat] = None
    for token in re.split(r'[+|,\s]+', text.strip().lower()):
        if token == '':
            continue
        try:
            flag = TickFormat[token.upper()]
        except KeyError:
            raise ValueError("Unknown tick format: '%s'" % token)
        fmt = flag if fmt is None else fmt | flag
    return fmt


def config_path(explicit: Optional[str]) -> Optional[str]:
    """Return the configuration file path to use, if any."""
    if explicit:
        return explicit
    env = os.environ.get('OVS_WATCH_CONF')
    if env:
        return env
    default = os.path.expanduser('~/.config/ovs-watch.conf')
    return default if os.path.exists(default) else None


def load_config(path: str,
                columns: Dict[str, Column],
                dashboards: Dict[str, Dashboard]) -> None:
    """Merge custom columns and dashboards from 'path' into the registries.

    'column <name>' sections define custom columns; 'dashboard <name>'
    sections define custom dashboards.  Both override built-ins of the same
    name."""
    parser = configparser.ConfigParser(interpolation=None)
    with open(path, encoding='utf-8') as f:
        parser.read_file(f)

    for section in parser.sections():
        kind, _, name = section.partition(' ')
        name = name.strip()
        if not name:
            continue
        opts = parser[section]
        if kind == 'column':
            histogram = opts.get('histogram', '').strip()
            if histogram:
                columns[name] = Histogram(
                    name=name,
                    metric=histogram,
                    unit=opts.get('unit', ''),
                    page=parse_page(opts.get('page', 'default')),
                )
                continue
            precision = opts.getint('precision', 0)
            power = opts.getint('power', 1000)
            if power not in (1000, 1024):
                raise ValueError(
                    "column %s: power must be 1000 or 1024" % name)
            if precision < 0:
                raise ValueError(
                    "column %s: precision must not be negative" % name)
            sources = parse_sources(opts.get('sources', ''))
            if not sources:
                raise ValueError(
                    "column %s: at least one source is required" % name)
            columns[name] = TimeSeries(
                name=name,
                unit=opts.get('unit', ''),
                sources=sources,
                operator=OPERATORS[opts.get('operator', 'sub')],
                derivative=opts.getboolean('derivative', False),
                precision=precision,
                power=power,
                tick_format=parse_tick_format(opts.get('tick_format', '')),
                page=parse_page(opts.get('page', 'default')),
            )
        elif kind == 'dashboard':
            dashboards[name] = Dashboard(
                name=name,
                title=opts.get('title', name),
                description=opts.get('description', ''),
                aliases=parse_list(opts.get('aliases', '')),
                columns=parse_list(opts.get('columns', '')),
            )


def dashboard_page(dashboard: Dashboard,
                   columns: Dict[str, Column]) -> MetricsPage:
    """Return the union of metrics pages required by 'dashboard'."""
    page = MetricsPage.DEFAULT
    for name in dashboard.columns:
        column = columns.get(name)
        if column is not None:
            page |= column.page
    return page


class KeyPoller:
    """Non-blocking single-key reader for an interactive terminal.

    Outside a TTY (or when disabled) poll() always returns None and the
    terminal is left untouched."""

    def __init__(self, enabled: bool) -> None:
        self.enabled = enabled and sys.stdin.isatty()
        self.fd: Optional[int] = None
        self.old: object = None

    def __enter__(self) -> "KeyPoller":
        if not self.enabled:
            return self
        try:
            import termios
            import tty
            self.fd = sys.stdin.fileno()
            self.old = termios.tcgetattr(self.fd)
            tty.setcbreak(self.fd)
        except Exception:
            self.enabled = False
        return self

    def __exit__(self, *exc) -> None:
        self.restore()

    def restore(self) -> None:
        """Restore the terminal to its original settings."""
        if self.fd is not None and self.old is not None:
            import termios
            termios.tcsetattr(self.fd, termios.TCSADRAIN, self.old)
            self.fd = None

    def poll(self) -> Optional[str]:
        """Return a pending key press, or None if none is available."""
        if not self.enabled or self.fd is None:
            return None
        readable, _, _ = select.select([sys.stdin], [], [], 0)
        if readable:
            return sys.stdin.read(1)
        return None


# Maps a series name to its retained samples.
History = Dict[str, Sequence[float]]


def _series_span(history: History, series: List[SeriesView]
                 ) -> Optional[Tuple[float, float]]:
    """Return the '(min, max)' across every value of every series in 'series'
    that holds samples, or None when none do.  Kept pure (no plotext state) so
    a pre-pass can size a shared axis gutter before any drawing."""
    lo: Optional[float] = None
    hi: Optional[float] = None
    for view in series:
        hist = history.get(view.name)
        if not hist:
            continue
        for value in hist:
            val = value * view.sign
            lo = val if lo is None else min(lo, val)
            hi = val if hi is None else max(hi, val)
    return None if lo is None else (lo, hi)


def _stat_window(values: Sequence[float],
                 window: Optional[int]) -> Sequence[float]:
    """Return the most recent 'window' samples of 'values', or all of them
    when 'window' is unset."""
    if window is not None and window > 0:
        return values[-window:]
    return values


def _mean_stdev(values: Sequence[float]) -> Tuple[float, float]:
    """Return the arithmetic '(mean, sample standard deviation)' of 'values',
    the deviation being zero for fewer than two samples."""
    n = len(values)
    mean = sum(values) / n
    variance = (sum((v - mean) ** 2 for v in values) / (n - 1)
                if n > 1 else 0.0)
    return mean, math.sqrt(variance)


def _ema_mean_stdev(values: Sequence[float], n: int) -> Tuple[float, float]:
    """Return the exponential-moving-average '(mean, standard deviation)' of
    'values'.  The smoothing factor is 2/(N+1) for a 'window' of N (defaulting
    to the sample count), matching an N-sample average's centre of mass."""
    alpha = 2.0 / (n + 1.0)
    mean = 0.0
    variance = 0.0
    for i, value in enumerate(values):
        if i == 0:
            mean = value
            continue
        diff = value - mean
        step = alpha * diff
        variance = (1.0 - alpha) * (variance + step * diff)
        mean += step
    return mean, math.sqrt(variance)


def series_stats_label(name: str, values: Sequence[float], stats: StatFlags,
                       window: Optional[int] = None) -> str:
    """Return the legend label for a series 'name' summarising 'values' per
    'stats'.  Compact 'μ' and '±' labels keep terminal legends narrow, while
    'ema(N)' exposes the smoothing window.  'window' bounds the samples
    considered.  Returns the bare 'name' when no statistic is requested or
    'values' is empty."""
    centre_flags = StatFlags.MEAN | StatFlags.SD | StatFlags.EMA
    if not values or not stats & centre_flags:
        return name
    if window is not None and window > 0:
        n = min(window, len(values))
    else:
        n = len(values)
    if StatFlags.EMA in stats:
        centre, sd = _ema_mean_stdev(values, n)
        parts = ['ema({:d}) {:.1f}'.format(n, centre)]
    elif StatFlags.MEAN in stats:
        centre, sd = _mean_stdev(_stat_window(values, n))
        parts = ['μ {:.1f}'.format(centre)]
    else:
        _, sd = _mean_stdev(_stat_window(values, n))
        parts = []
    if StatFlags.SD in stats:
        parts.append(('± {:.1f}' if parts else 'sd {:.1f}').format(sd))
    return '{} ({})'.format(name, ' '.join(parts))


def _draw_series(history: History, xs: Sequence[float],
                 series: List[SeriesView], stats: StatFlags, side: str,
                 stats_window: Optional[int] = None
                 ) -> Optional[Tuple[float, float]]:
    """Plot each series of 'series' against the sample times 'xs' on the 'side'
    ('left'/'right') y-axis and return the '(min, max)' of every plotted value,
    or None when no series held any samples.

    A view's 'marker' overrides the side's default plot style
    ('DEFAULT_MARKER') when set.  'stats' is the graph's default set of legend
    statistics; a view's own 'stats' overrides it for that series.
    'stats_window' bounds the samples every series' statistics consider.
    Statistics are computed on the series' real magnitudes, not their plotting
    sign."""
    for view in series:
        marker = (view.marker if view.marker is not None
                  else DEFAULT_MARKER[side])
        hist = history.get(view.name)
        if not hist:
            continue
        values = [v * view.sign for v in hist]
        view_stats = view.stats if view.stats is not None else stats
        label = series_stats_label(view.name, list(hist), view_stats,
                                   stats_window)
        plt.plot(list(xs), values, label=label, marker=marker, yside=side)
    return _series_span(history, series)


def axis_format(series: List[SeriesView],
                columns: Dict[str, TimeSeries],
                override: Optional[TickFormat]
                ) -> Tuple[TickFormat, int, int]:
    """Resolve '(tick format, scaling base, log base)' for an axis carrying
    'series', from the plotted columns.

    SI columns (base 1000, log10) win over binary ones (base 1024, log2) when
    an axis mixes the two, and FLOAT wins over INT so shared rate/count axes
    keep fractional detail.  Absent an 'override' the axis is SCALED."""
    cols = [columns[v.name] for v in series if v.name in columns]
    power = 1000 if any(c.power == 1000 for c in cols) or not cols else 1024
    base = 10 if power == 1000 else 2
    if override is not None:
        return override, power, base
    fmt = TICK_FORMAT_INT
    if any(c.tick_format & TICK_FORMAT_FLOAT for c in cols):
        fmt = TICK_FORMAT_FLOAT
    return fmt | TICK_FORMAT_SCALED, power, base


def series_polarity(series: List[SeriesView]) -> Tuple[bool, bool]:
    """Return '(has_up, has_down)' from the directions in 'series'.

    A series tracks the derivative of a monotonic counter, so it can only move
    in the direction of its view; that fixes an axis' polarity regardless of
    the current (possibly all-zero) values."""
    has_up = any(v.direction is Direction.UP for v in series)
    has_down = any(v.direction is Direction.DOWN for v in series)
    return has_up, has_down


def _baseline_span(span: Optional[Tuple[float, float]], scale: str,
                   has_up: bool, has_down: bool
                   ) -> Optional[Tuple[float, float]]:
    """Pin zero on a linear axis from the directions its series may take, so
    placement is stable even while every value is still zero: centered for a
    diverging axis (some up, some down), at the bottom for an up-only axis, at
    the top for a down-only axis.  Returns the span to label, pure so both the
    gutter pre-pass and the draw pass agree on the labels."""
    if span is None or scale == "log":
        return span
    lo, hi = span
    if has_up and has_down:
        bound = max(abs(lo), abs(hi), 1.0)
        return (-bound, bound)
    if has_up:
        return (0.0, hi if hi > 0 else 1.0)
    if has_down:
        return (lo if lo < 0 else -1.0, 0.0)
    return span


def _anchor_baseline(span: Optional[Tuple[float, float]], scale: str,
                     side: str, has_up: bool, has_down: bool
                     ) -> Optional[Tuple[float, float]]:
    """Pin the 'side' y-axis baseline via '_baseline_span', applying the
    resulting limits to plotext, and return the span to label."""
    result = _baseline_span(span, scale, has_up, has_down)
    if result is not None and scale != "log" and (has_up or has_down):
        plt.ylim(result[0], result[1], yside=side)
    return result


def _axis_labels(history: History, series: List[SeriesView],
                 scale: str, columns: Dict[str, TimeSeries],
                 override: Optional[TickFormat],
                 signed: bool = False) -> List[str]:
    """Return the y-tick label strings an axis carrying 'series' will show, or
    [] when it holds no samples.  Used to size a uniform gutter before drawing
    so stacked graphs share the same canvas columns (aligned x-axes).  Mirrors
    the 'signed' handling of '_apply_ticks' so the pre-pass sizes the same
    labels the draw pass emits."""
    has_up, has_down = series_polarity(series)
    span = _baseline_span(_series_span(history, series), scale,
                          has_up, has_down)
    if span is None:
        return []
    fmt, power, base = axis_format(series, columns, override)
    ticks = axis_ticks(span[0], span[1], scale, base=base)
    return [format_tick(t if signed else abs(t), fmt, power) for t in ticks]


def _apply_ticks(span: Optional[Tuple[float, float]], scale: str,
                 fmt: TickFormat, power: int, base: int, side: str,
                 gutter: int = 0, signed: bool = False) -> None:
    """Relabel the 'side' y-axis ticks spanning 'span' with 'fmt'/'power',
    spacing them by powers of 'base'.  An empty 'span' is left alone.  When
    'gutter' is set each label is padded to that width (right-aligned on the
    left axis, left-aligned on the right) so every graph reserves the same
    label column budget and their canvases line up.  Unless 'signed', a
    mirrored (below-baseline) tick is labeled with its absolute magnitude, as
    its value is a counter derivative that is only plotted negative."""
    if span is None:
        return
    ticks = axis_ticks(span[0], span[1], scale, base=base)
    labels = [format_tick(t if signed else abs(t), fmt, power) for t in ticks]
    if gutter > 0:
        labels = [s.rjust(gutter) if side == "left" else s.ljust(gutter)
                  for s in labels]
    plt.yticks(ticks, labels, yside=side)


def _reserve_right_gutter(width: int) -> None:
    """Draw an invisible right-axis series so a graph without right-hand data
    still reserves 'width' columns of right gutter, keeping its canvas (and
    thus its x-axis) aligned with graphs that do carry a right axis."""
    plt.plot([0.0, 0.0], marker=" ", yside="right")
    plt.ylim(0.0, 1.0, yside="right")
    plt.yticks([0.0, 1.0], [" " * width, " " * width], yside="right")


def _apply_xaxis(xs: Sequence[float], window: float, scale: str) -> None:
    """Anchor the x-axis to the sample times 'xs' so time (not the sample
    index) is shown and keeps advancing once the history is full.

    On a linear axis the window keeps a fixed 'window'-second span: the newest
    sample sits at the right edge and older samples translate left, so the
    graph does not rescale as it fills; once it holds a full 'window' of data
    it scrolls with time.  Only ticks at non-negative times are labeled, so the
    still-empty region left of time zero stays blank during the fill."""
    if not xs or scale != "linear":
        return
    hi = xs[-1]
    # A positive 'window' fixes the span so the view scrolls without rescaling
    # once full; without one, fall back to the data span.
    lo = hi - (window if window > 0 else hi - xs[0])
    plt.xlim(lo, hi)
    ticks = [t for t in axis_ticks(lo, hi, scale) if t >= 0]
    plt.xticks(ticks, [format_time_tick(t) for t in ticks])


def build_graph_block(graph: GraphSpec, history: History,
                      xs: Sequence[float], columns: Dict[str, TimeSeries],
                      width: int, height: int, window: float = 0.0,
                      gutter_left: int = 0, gutter_right: int = 0) -> str:
    """Render 'graph' to a plotext frame string 'width' by 'height' cells,
    plotting every series against the sample times 'xs'.  'window' is the
    x-axis span, in seconds, held fixed while the history fills.

    'gutter_left' and 'gutter_right' force the width, in columns, reserved for
    the left and right y-tick labels, so a set of stacked graphs share the
    same canvas span and their x-axes align.

    Kept separate from the live display so each graph (and its axis options)
    can be rendered and asserted on in isolation."""
    plt.clf()
    plt.theme("dark")
    plt.plotsize(width, height)
    plt.title(graph.title)
    left = _draw_series(history, xs, graph.series, graph.stats, "left",
                        graph.stats_window)
    plt.xscale(graph.xscale)
    plt.yscale(graph.yscale)
    up, down = series_polarity(graph.series)
    left = _anchor_baseline(left, graph.yscale, "left", up, down)
    fmt, power, base = axis_format(graph.series, columns, graph.ytick_format)
    _apply_ticks(left, graph.yscale, fmt, power, base, "left", gutter_left,
                 graph.ysigned)
    right = None
    if graph.right_series:
        right = _draw_series(history, xs, graph.right_series, graph.stats,
                             "right", graph.stats_window)
        plt.yscale(graph.right_yscale, yside="right")
        up, down = series_polarity(graph.right_series)
        right = _anchor_baseline(right, graph.right_yscale, "right", up, down)
        fmt, power, base = axis_format(graph.right_series, columns,
                                       graph.right_ytick_format)
        _apply_ticks(right, graph.right_yscale, fmt, power, base, "right",
                     gutter_right, graph.right_ysigned)
    if right is None and gutter_right > 0:
        _reserve_right_gutter(gutter_right)
    _apply_xaxis(xs, window, graph.xscale)
    return plt.build()


def build_hist_block(hist: Histogram, width: int, height: int) -> str:
    """Render histogram column 'hist' to a plt.hist frame string 'width' by
    'height' cells, titled with its current mean and standard deviation."""
    plt.clf()
    plt.theme("dark")
    plt.plotsize(width, height)
    title = hist.name
    if hist.count > 0:
        title = '{} (mean {:.1f} sd {:.1f} {})'.format(
            hist.name, hist.mean, hist.stdev, hist.unit).strip()
    plt.title(title)
    data = histogram_samples(hist.edges, hist.counts, HIST_MAX_SAMPLES)
    if data:
        plt.hist(data, bins=max(1, len(hist.edges)), marker=MARKER_BRAILLE)
    return plt.build()


class Watcher:
    """Drives metric collection and rendering for one dashboard."""

    def __init__(self, dashboard: Dashboard,
                 columns: Dict[str, Column],
                 args: argparse.Namespace,
                 outfile: Optional[TextIO]) -> None:
        self.dashboard = dashboard
        self.args = args
        self.outfile = outfile
        self.columns: List[Column] = [
            deepcopy(columns[name]) for name in dashboard.columns
            if name in columns
        ]
        self.column_map: Dict[str, Column] = {
            col.name: col for col in self.columns
        }
        self.history: Dict[str, Deque[float]] = {
            col.name: deque(maxlen=GRAPH_HISTORY) for col in self.columns
        }
        self.times: Deque[float] = deque(maxlen=GRAPH_HISTORY)
        self.histograms: List[Histogram] = [
            col for col in self.columns if isinstance(col, Histogram)
        ]
        scalar = [col for col in self.columns
                  if not isinstance(col, Histogram)]
        self.graphs = dashboard.graphs or auto_graphs(scalar)
        page = dashboard_page(dashboard, columns)
        self.wait_column: Optional[TimeSeries] = None
        if args.wait_column is not None and args.wait_column in columns:
            self.wait_column = deepcopy(columns[args.wait_column])
            page |= self.wait_column.page
        self.db = MetricsDB(page=page)
        self.graphical = (bool(getattr(args, 'graph', False))
                          and HAVE_PLOTEXT and sys.stdout.isatty())
        self.clear_line = '\033[K'
        self.graph_drawn = False
        # Period actually used by the sampling loop, which 'MetricsDB.wait()'
        # may raise above the requested 'args.period'.  The graph x-axis window
        # is derived from this so it matches the real sample spacing.
        self.effective_period_ms: float = float(getattr(args, 'period', 1000))

    def header(self) -> str:
        cells = ' '.join(col.legend() for col in self.columns)
        return '    time ' + cells

    def units(self) -> str:
        cells = ' '.join(col.unit_label() for col in self.columns)
        return '  second ' + cells

    def write_csv_header(self) -> None:
        if self.outfile is None:
            return
        legend = 'time\t' + '\t'.join(c.legend() for c in self.columns)
        units = 'second\t' + '\t'.join(c.unit_label() for c in self.columns)
        self.outfile.write(legend + '\n')
        self.outfile.write(units + '\n')

    def record_history(self) -> None:
        for col in self.columns:
            self.history[col.name].append(col.value)
        self.times.append(self.db.last_ts() / 1000)

    def render_text(self, sec: str, count: int) -> None:
        if self.graph_drawn:
            sys.stdout.write('\033[?7h\033[?25h\033[?1049l')
            self.graph_drawn = False
            print(self.header())
        if count != 0 and count % 10 == 0:
            print(self.header())
        values = ' '.join(col.format_human() for col in self.columns)
        print(sec + ' ' + values, flush=True)

    def write_csv_row(self, sec: str) -> None:
        """Append one measure row to the CSV output, independent of the display
        mode so '-o' keeps recording while the graphical view is shown."""
        if self.outfile is None:
            return
        csv = '\t'.join(col.format_csv() for col in self.columns)
        self.outfile.write(sec + '\t' + csv + '\n')

    def series_disabled(self, view: SeriesView) -> bool:
        """Whether 'view's column is disabled, i.e. one of its sources is
        absent for the running configuration (e.g. a hardware-offload metric
        while offload is off)."""
        col = self.column_map.get(view.name)
        return col is not None and col.disabled

    def active_graphs(self) -> List[GraphSpec]:
        """Return the graphs to render, with every series whose column is
        disabled dropped and any graph thereby left empty omitted.

        A metric that is invalid for the running configuration would otherwise
        be plotted as a flat zero line, indistinguishable from a real zero, so
        it is skipped instead."""
        active = []
        for graph in self.graphs:
            left = [v for v in graph.series if not self.series_disabled(v)]
            right = [v for v in graph.right_series
                     if not self.series_disabled(v)]
            if not left and not right:
                continue
            active.append(replace(graph, series=left, right_series=right))
        return active

    def graph_gutters(self, graphs: List[GraphSpec]) -> Tuple[int, int]:
        """Return the '(left, right)' y-tick label widths to reserve on every
        graph of 'graphs', taken as the widest such label across them, so their
        canvases share the same columns and the x-axes align.  The right
        gutter is 0 when no graph carries a right axis."""
        left = 0
        right = 0
        for graph in graphs:
            labels = _axis_labels(self.history, graph.series, graph.yscale,
                                  self.column_map, graph.ytick_format,
                                  graph.ysigned)
            left = max([left] + [len(s) for s in labels])
            if graph.right_series:
                labels = _axis_labels(self.history, graph.right_series,
                                      graph.right_yscale, self.column_map,
                                      graph.right_ytick_format,
                                      graph.right_ysigned)
                right = max([right] + [len(s) for s in labels])
        return left, right

    def render_graph(self, sec: str, count: int) -> None:
        if plt is None or (not self.graphs and not self.histograms):
            return
        size = shutil.get_terminal_size((120, 40))
        if size.columns < GRAPH_MIN_WIDTH:
            self.render_text(sec, count)
            return
        graphs = self.active_graphs()
        histograms = [h for h in self.histograms if not h.disabled]
        panes = len(graphs) + len(histograms)
        if panes == 0:
            # Every graphed metric is invalid for this configuration, so the
            # graphical view would be blank; show the text view instead.
            self.render_text(sec, count)
            return
        body = max(1, size.lines - 1)
        # Build each graph on its own and stack the pieces by hand instead of
        # using plotext subplots().  When the combined subplots do not fit the
        # pane plotext renders the last one repeatedly and garbles the frame;
        # short tmux panes hit this constantly.  A fixed per-graph height also
        # keeps the total bounded so the frame always fits.
        per = max(3, body // panes)
        width = size.columns
        gutter_left, gutter_right = self.graph_gutters(graphs)
        xs = list(self.times)
        # A full history of GRAPH_HISTORY samples spans one fewer interval, so
        # sizing the window by intervals avoids a permanent empty left slice.
        window = (GRAPH_HISTORY - 1) * self.effective_period_ms / 1000
        blocks = [build_graph_block(graph, self.history, xs, self.column_map,
                                    width, per, window,
                                    gutter_left, gutter_right)
                  for graph in graphs]
        blocks += [build_hist_block(hist, width, per)
                   for hist in histograms]
        lines: List[str] = []
        for block in blocks:
            rows = block.split('\n')
            if rows and not rows[-1]:
                rows.pop()
            lines.extend((rows + [''] * per)[:per])
        lines = (lines + [''] * body)[:body]
        out = []
        if not self.graph_drawn:
            # Draw on the alternate screen buffer, the way top/vim/less do, so
            # the text view is restored untouched on exit.  Also hide the
            # cursor and disable line wrap.
            out.append('\033[?1049h\033[?25l\033[?7l')
            self.graph_drawn = True
        for index, line in enumerate(lines):
            out.append('\033[%d;1H%s' % (index + 1, line))
        out.append('\033[%d;1H[d] toggle display  [q] quit\033[K' % size.lines)
        sys.stdout.write(''.join(out))
        sys.stdout.flush()

    def handle_key(self, key: Optional[str]) -> bool:
        """Act on a key press.  Returns False when the watcher should stop."""
        if key in ('q', 'Q'):
            return False
        if key in ('d', 'D') and HAVE_PLOTEXT and sys.stdout.isatty():
            self.graphical = not self.graphical
        return True

    def run(self) -> None:
        period = self.args.period
        self.write_csv_header()
        interactive = sys.stdout.isatty()

        try:
            self._loop(interactive, period)
        finally:
            if self.graph_drawn:
                sys.stdout.write('\033[?7h\033[?25h\033[?1049l')
                sys.stdout.flush()

    def _loop(self, interactive: bool, period: int) -> None:
        started = False
        count = 0
        with KeyPoller(interactive) as keys:
            print(self.header())
            print(self.units(), flush=True)
            while True:
                if not self.handle_key(keys.poll()):
                    break
                try:
                    self.db.update()
                except MetricsReadError:
                    print('%sFailed to read OVS metrics, retrying...'
                          % self.clear_line, end='\r')
                    self.db.reset()
                    for samples in self.history.values():
                        samples.clear()
                    self.times.clear()
                    period = self.db.wait(period)
                    self.effective_period_ms = period
                    count = 0
                    started = False
                    continue

                for col in self.columns:
                    col.update(self.db)

                if self.wait_column is not None and not started:
                    self.wait_column.update(self.db)
                    if self.wait_column.value == 0:
                        print('%sWaiting for %s.'
                              % (self.clear_line, self.wait_column.name),
                              end='\r')
                        period = self.db.wait(period)
                        self.effective_period_ms = period
                        continue
                    started = True

                self.record_history()
                sec = '{:08.3f}'.format(self.db.last_ts() / 1000)
                self.write_csv_row(sec)
                if self.graphical:
                    self.render_graph(sec, count)
                else:
                    self.render_text(sec, count)
                count += 1
                period = self.db.wait(period)
                self.effective_period_ms = period


def list_columns(columns: Dict[str, Column]) -> None:
    """Print every available column with its unit and sources."""
    for name in sorted(columns):
        col = columns[name]
        if isinstance(col, Histogram):
            kind = 'hist'
        elif col.derivative:
            kind = 'rate'
        else:
            kind = 'value'
        srcs = ', '.join(r.name for r in col.sources)
        print('{:>18}  {:<5}  {:<6}  {}'.format(
            name, col.unit or '-', kind, srcs))


def list_dashboards(dashboards: Dict[str, Dashboard]) -> None:
    """Print every available dashboard with its shorthand and description."""
    for name in sorted(dashboards):
        dash = dashboards[name]
        alias = ', '.join(dash.aliases) if dash.aliases else '-'
        print('{:>18}  {:<5}  {}'.format(name, alias, dash.description))


def match_name(token: str, names: Sequence[str]) -> Optional[str]:
    """Resolve 'token' against 'names' by exact match, or failing that by
    unique prefix.  Return the matched name, None when nothing matches, or
    raise ValueError when the prefix is ambiguous."""
    if token in names:
        return token
    matches = sorted(name for name in names if name.startswith(token))
    if len(matches) == 1:
        return matches[0]
    if not matches:
        return None
    raise ValueError("'%s' matches %s" % (token, ', '.join(matches)))


def resolve_dashboard(args: argparse.Namespace,
                      columns: Dict[str, Column],
                      dashboards: Dict[str, Dashboard]) -> Dashboard:
    """Select or compose the dashboard requested on the command line."""
    if args.columns:
        names = parse_list(args.columns)
        unknown = [n for n in names if n not in columns]
        if unknown:
            sys.stderr.write("Unknown column(s): %s\n" % ', '.join(unknown))
            sys.exit(1)
        return Dashboard(name='custom', title='Custom', columns=names)

    requested = args.dashboard or args.dashboard_pos or 'offloads'
    try:
        name = resolve_dashboard_name(requested, dashboards)
    except ValueError as e:
        sys.stderr.write("Ambiguous dashboard %s.\n" % e)
        sys.exit(1)
    if name is None:
        sys.stderr.write("Unknown dashboard: '%s'.\n" % requested)
        sys.exit(1)
    return dashboards[name]


def resolve_dashboard_name(token: str,
                           dashboards: Dict[str, Dashboard]) -> Optional[str]:
    """Resolve 'token' to a dashboard name: by exact name, then by exact
    shorthand alias, then by unique name prefix.  Return None when nothing
    matches, or raise ValueError when a prefix is ambiguous."""
    if token in dashboards:
        return token
    for name, dashboard in dashboards.items():
        if token in dashboard.aliases:
            return name
    return match_name(token, list(dashboards))


def parse_args() -> argparse.Namespace:
    graph_state = 'available' if HAVE_PLOTEXT else 'NOT available'
    graph_help = ''
    if not HAVE_PLOTEXT:
        graph_help = (' (requires the plotext module, currently %s.)'
                      % graph_state)
    parser = argparse.ArgumentParser(
        description='Open vSwitch metrics dashboard viewer.',
        epilog='Graphical mode (the -g option or the "d" key) requires the '
               'plotext python module, currently %s.' % graph_state)
    parser.add_argument('--version', action='version', version='3.6.0038')
    parser.add_argument('dashboard_pos', metavar='DASHBOARD', nargs='?',
                        help='dashboard to display, by full name or any '
                             'unambiguous prefix (default: offloads)')
    parser.add_argument('-D', '--dashboard', metavar='NAME',
                        help='dashboard to display, same as the positional '
                             'argument (default: offloads)')
    parser.add_argument('--columns', metavar='A,B,C',
                        help='compose an ad-hoc dashboard from these columns')
    parser.add_argument('--list-dashboards', action='store_true',
                        help='list available dashboards and exit')
    parser.add_argument('--list-columns', action='store_true',
                        help='list available columns and exit')
    parser.add_argument('--config', metavar='FILE',
                        help='configuration file with custom dashboards')
    parser.add_argument('-p', '--period', type=int, default=1000,
                        metavar='MS', help='metrics query periodicity')
    parser.add_argument('-o', '--output', dest='outfile', metavar='FILE.CSV',
                        help='also write measures to a CSV file')
    parser.add_argument('-w', '--wait', dest='wait_column',
                        nargs='?', const='sw-rx-pps', default=None,
                        metavar='COLUMN',
                        help='wait until COLUMN is first active before '
                             'displaying (default column: sw-rx-pps)')
    parser.add_argument('-g', '--graph', action='store_true',
                        help='start in graphical mode%s' % graph_help)
    return parser.parse_args()


def main() -> int:
    args = parse_args()

    columns = build_columns()
    dashboards = build_dashboards()

    path = config_path(args.config)
    if path:
        try:
            load_config(path, columns, dashboards)
        except (configparser.Error, ValueError, KeyError, OSError,
                UnicodeError) as e:
            sys.stderr.write("Failed to read config '%s': %s\n" % (path, e))
            return 1

    if args.graph and not HAVE_PLOTEXT:
        if PLOTEXT_IMPORT_ERROR is None:
            sys.stderr.write(
                "Graphical mode requires the plotext python module, which is "
                "not installed; falling back to text mode.\n")
        else:
            sys.stderr.write(
                "Graphical mode failed to import plotext: %s; falling back "
                "to text mode.\n" % PLOTEXT_IMPORT_ERROR)
    elif args.graph and not sys.stdout.isatty():
        sys.stderr.write(
            "Graphical mode requires a terminal on standard output; "
            "falling back to text mode.\n")

    if args.list_dashboards:
        list_dashboards(dashboards)
        return 0
    if args.list_columns:
        list_columns(columns)
        return 0

    dashboard = resolve_dashboard(args, columns, dashboards)

    if args.wait_column is not None:
        try:
            name = match_name(args.wait_column, list(columns))
        except ValueError as e:
            sys.stderr.write("Ambiguous column %s.\n" % e)
            return 1
        if name is None:
            sys.stderr.write("Unknown column: '%s'.\n" % args.wait_column)
            return 1
        args.wait_column = name

    outfile: Optional[TextIO] = None
    if args.outfile:
        try:
            outfile = open(args.outfile, 'w')
        except OSError as e:
            sys.stderr.write(
                "Failed to open '%s': %s.\n" % (e.filename, e.strerror))
            return 1

    watcher = Watcher(dashboard, columns, args, outfile)
    try:
        watcher.run()
    finally:
        if outfile is not None:
            outfile.close()
    return 0


def sigint_handler(sig, frame) -> None:
    sys.exit(0)


if __name__ == '__main__':
    signal.signal(signal.SIGINT, sigint_handler)
    sys.exit(main())

# vi: filetype=python
