NMS-20032: implement a postgresql-based Flows feature

container/features/src/main/resources/features-sentinel.xml

@@ -160,6 +160,24 @@
         <bundle>mvn:org.opennms.features.distributed/org.opennms.features.distributed.collection/${project.version}</bundle>
     </feature>
 
+    <feature name="sentinel-flows-postgres" start-level="${earlyStartLevel}" version="${project.version}" description="OpenNMS :: Sentinel :: Flows :: Postgres">
+        <details>Optional PostgreSQL-backed flow persistence for Sentinel (write path). When installed it registers a
+            higher-ranked FlowRepository that overrides Elasticsearch persistence on this Sentinel; flow reads are
+            served by Horizon against the same database. Optional write-time aggregation into flow_agg can be enabled
+            per Sentinel (aggregation.enabled=true with a distinct aggregation.writerId). Configure the flow database
+            via the org.opennms.features.flows.persistence.postgres pid (datasource.url/username/password/databaseName).</details>
+        <feature>sentinel-flows</feature>
+        <feature version="[5.3,5.4)">spring-jdbc</feature>
+        <!-- HikariCPConnectionFactory + JdbcDataSource config model + PostgreSQL driver for the dedicated flow pool -->
+        <feature>opennms-core-db</feature>
+        <!-- opennms-health-api provides the HealthCheck SPI for the flow-database health check -->
+        <feature>opennms-health-api</feature>
+        <bundle dependency="true">mvn:com.fasterxml.jackson.core/jackson-databind/${jackson2Version}</bundle>
+        <bundle dependency="true">mvn:org.yaml/snakeyaml/1.31</bundle>
+        <bundle>mvn:org.liquibase/liquibase-core/${liquibaseVersion}</bundle>
+        <bundle>mvn:org.opennms.features.flows/org.opennms.features.flows.postgres/${project.version}</bundle>
+    </feature>
+
     <feature name="sentinel-telemetry-nxos" start-level="${earlyStartLevel}" description="OpenNMS :: Sentinel :: Telemetry :: Adapters :: NXOS" version="${project.version}">
         <feature>sentinel-telemetry</feature>
         <feature>opennms-telemetry-nxos</feature>

container/features/src/main/resources/features.xml

@@ -1207,6 +1207,24 @@
         <bundle>mvn:org.opennms.features.flows.classification/org.opennms.features.flows.classification.shell/${project.version}</bundle>
         <bundle>mvn:org.opennms.features.telemetry.protocols.netflow.xml/org.opennms.features.telemetry.protocols.netflow.xml.core/${project.version}</bundle>
     </feature>
+    <feature name="opennms-flows-postgres" start-level="${earlyStartLevel}" version="${project.version}" description="OpenNMS :: Features :: Flows :: Postgres">
+        <details>Optional PostgreSQL-backed FlowRepository/FlowQueryService (jsonb). Install alongside or instead of the Elasticsearch flow persistence.</details>
+        <feature>opennms-flows</feature>
+        <feature version="[5.3,5.4)">spring-jdbc</feature>
+        <!-- opennms-core-db provides HikariCPConnectionFactory + the JdbcDataSource config model + the
+             PostgreSQL driver, used to build the dedicated flow connection pool in the bundle blueprint. -->
+        <feature>opennms-core-db</feature>
+        <!-- opennms-health-api provides the HealthCheck SPI for the flow-database health check -->
+        <feature>opennms-health-api</feature>
+        <bundle dependency="true">mvn:com.fasterxml.jackson.core/jackson-databind/${jackson2Version}</bundle>
+        <!-- liquibase-core 3.6.3 is already an OSGi bundle whose manifest mandatorily imports
+             org.yaml.snakeyaml [1.18,2.0); the rest of OpenNMS ships snakeyaml 2.x (out of range),
+             so pin a 1.x jar for liquibase to wire to. Reference liquibase-core as a plain bundle:
+             pax-url wrap: does not rewrite an existing bundle manifest. -->
+        <bundle dependency="true">mvn:org.yaml/snakeyaml/1.31</bundle>
+        <bundle>mvn:org.liquibase/liquibase-core/${liquibaseVersion}</bundle>
+        <bundle>mvn:org.opennms.features.flows/org.opennms.features.flows.postgres/${project.version}</bundle>
+    </feature>
     <feature name="opennms-api-layer" version="${project.version}" description="OpenNMS :: Features :: API Layer">
         <feature>opennms-health</feature>
         <feature>opennms-situation-feedback-api</feature>

docs/modules/development/pages/rest/flows.adoc

@@ -14,7 +14,7 @@ NOTE: Unless otherwise specified, all units of time are expressed in millisecond
 | Resource  | Description
 
 | /flows/count
-| Retrieve the number of flows available.
+| Retrieve the number of flows available. With no query parameters, the default filter is the previous four hours.
 
 | /flows/exporters
 | Retrieve basic information for the exporter nodes that have flows available.

docs/modules/operation/nav.adoc

@@ -189,6 +189,7 @@
 
 ** xref:deep-dive/flows/introduction.adoc[]
 *** xref:deep-dive/flows/basic.adoc[]
+*** xref:deep-dive/flows/elasticsearch.adoc[]
 *** xref:deep-dive/flows/distributed.adoc[]
 *** xref:deep-dive/flows/sentinel/sentinel.adoc[]
 *** xref:deep-dive/flows/classification-engine.adoc[]

docs/modules/operation/pages/deep-dive/flows/aggregation.adoc

@@ -4,7 +4,7 @@
 
 The flow query engine supports rendering the top _N_ metrics from pre-aggregated documents stored in Elasticsearch.
 You can use these statistics to help alleviate computation load on the Elasticsearch cluster, particularly in environments with large volumes of flows (more than 10,000 per second).
-To use this functionality, you must <<deep-dive/flows/basic.adoc#kafka-forwarder-config, enable the Kafka forwarder>> and set up the streaming analytics tool to process flows and persist aggregates in Elasticsearch.
+To use this functionality, you must <<deep-dive/flows/elasticsearch.adoc#kafka-forwarder-config, enable the Kafka forwarder>> and set up the streaming analytics tool to process flows and persist aggregates in Elasticsearch.
 
 Set the following properties in `$\{OPENNMS_HOME}/etc/org.opennms.features.flows.persistence.elastic.cfg` to control the query engine to use aggregated flows: