LABDCN-1038

Author: camrossi

docs/LABDCN-1038/README.md

@@ -0,0 +1,24 @@
+# LABDCN-1038: Open Source Monitoring for Cisco ACI
+
+This section contains specific instruction on how to run the *LABDCN-1038* Walk In Lab for Cisco Live San Diego 2025. 
+
+## Task 1 - Getting Familiar with the ACI Monitoring Stack
+
+If this is your first time learning about the ACI monitoring stack you should start with the [Overview](overview.md) that provides an overview of the Stack Architecture.
+You do not need to deep dive in the details, unless you want to, but is good to have a generic understanding of the components used in the Stack.
+
+Next head over the [Demo Environment](../demo-environment.md) documentation, as you read this section explore the dashboard that are available in the Demo Environment.
+
+## Task 2 - Create a Dashboard
+
+[Lab1](../labs/lab1.md): In this lab we are going to re-built the ACI Fault Dashboard
+
+## Task 3 - Explore The Logs
+
+[Lab2](../labs/lab2.md): In this lab we are going to use `Explore` to visualize the Logs Received by our ACI fabrics. 
+
+## Task 4 - Explore the ACI Configs
+
+The ACI Monitoring Stack introduced a new feature in its last release that automatically generates a Config Snapshot every 15 minutes (by default) and seamlessly loads it into a Graph Database. This allow the user to then query the ACI config directly from Grafana.
+
+[Lab3](../labs/lab3.md)

docs/LABDCN-1038/overview.md

@@ -0,0 +1,141 @@
+aci-monitoring-stack - Open Source Monitoring for Cisco ACI
+------------
+
+# Overview
+
+Harness the power of open source to efficiently monitor your Cisco ACI environment with the ACI-Monitoring-Stack. This lightweight, yet robust, monitoring solution combines top-tier open source tools, each contributing unique capabilities to ensure comprehensive visibility into your ACI infrastructure.
+
+The ACI-Monitoring-Stack integrates the following key components:
+
+- [Grafana](https://grafana.com/oss/grafana/): The leading open-source analytics and visualization platform. Grafana allows you to create dynamic dashboards that provide real-time insights into your network's performance, health, and metrics. With its user-friendly interface, you can easily visualize and correlate data across your ACI fabric, enabling quicker diagnostics and informed decision-making.
+
+- [Prometheus](https://prometheus.io/): A powerful open-source monitoring and alerting toolkit. Prometheus excels in collecting and storing metrics in a time-series database, allowing for flexible queries and real-time alerting. Its seamless integration with Grafana ensures that your monitoring stack provides a detailed and up-to-date view of your ACI environment.
+
+- [Loki](https://grafana.com/oss/loki/): Designed for efficiently aggregating and querying logs from your entire ACI ecosystem. Loki complements Prometheus by focusing on log aggregation, providing a unified stack for metrics and logs. Its integration with Grafana enables you to correlate log data with metrics and create a holistic monitoring experience.
+
+- [Promtail](https://grafana.com/docs/loki/latest/send-data/promtail/): the agent responsible for gathering and shipping the log files to the Loki server.
+
+- [Syslog-ng](https://github.com/syslog-ng/syslog-ng): is an open-source implementation of the Syslog protocol, its role in this stack is to translate syslog messages from RFC 3164 to 5424. This is needed because Promtail only support Syslog RFC 5424 over TCP and this capability is only available in ACI 6.1 and above.
+
+- [aci-exporter](https://github.com/opsdis/aci-exporter): A Prometheus exporter that serves as the bridge between your Cisco ACI environment and the Prometheus monitoring ecosystem. The aci-exporter translates ACI-specific metrics into a format that Prometheus can ingest, ensuring that all crucial data points are captured and monitored effectively.
+
+- [backup2graph](apps/backup2graph/README.md): Convert an ACI Backup into a Graph Database
+
+- [Memgraph](https://github.com/memgraph/memgraph): An open source graph database implemented in C/C++ and leverages an in-memory first architecture. This will be used in the ACI-Monitoring-Stack to explore the ACI configurations imported by backup2graph
+
+- Pre-configured ACI data collections queries, alerts, and dashboards (Work In Progress): The ACI-Monitoring-Stack provides a solid foundation for monitoring an ACI fabric with its pre-defined queries, dashboards, and alerts. While these tools are crafted based on best practices to offer immediate insights into network performance, they are not exhaustive. The strength of the ACI-Monitoring-Stack lies in its community-driven approach. Users are invited to contribute their expertise by providing feedback, sharing custom solutions, and helping enhance the stack. Your input helps to refine and expand the stack's capabilities, ensuring it remains a relevant and powerful tool for network monitoring.
+
+# Your Stack
+
+To gain a comprehensive understanding of the ACI Monitoring Stack and its components it is helpful to break down the stack into separate functions. Each function focuses on a different aspect of monitoring the Cisco Application Centric Infrastructure (ACI) environment.
+
+## Fabric Discovery:
+
+The ACI monitoring stack uses Prometheus Service Discovery (HTTP SD) to dynamically discover and scrape targets by periodically querying a specified HTTP endpoint for a list of target configurations in JSON format.
+
+The ACI Monitoring Stack needs only the IP addresses of the APICs, the Switches will be Auto Discovered. If switches are added or removed from the fabric no action is required from the end user.
+
+```mermaid
+    flowchart-elk RL
+      P[("Prometheus")]
+      A["aci-exporter"]
+      APIC["APIC"]
+
+      APIC -- "API Query" --> A
+      A -- "HTTP SD" --> P
+```
+
+## ACI Object Scraping: 
+
+`Prometheus` scraping is the process by which `Prometheus` periodically collects metrics data by sending HTTP requests to predefined endpoints on monitored targets. The `aci-exporter` translates ACI-specific metrics into a format that `Prometheus` can ingest, ensuring that all crucial data points are captured and monitored effectively.
+
+```mermaid
+    flowchart-elk RL
+      P[("Prometheus")]
+      A["aci-exporter"]
+      subgraph ACI
+        S["Switches"]
+        APIC["APIC"]
+      end
+      A--"Scraping"-->P
+      S--"API Queries"-->A
+      APIC--"API Queries"-->A
+```
+## Syslog Ingestion:
+
+The syslog config is composed of 3 components: `promtail`, `loki` and `syslog-ng`.
+Prior to ACI 6.1 `syslog-ng` is required between `ACI` and `Promtail` to convert from RFC 3164 to 5424 syslog message format.
+
+```mermaid
+    flowchart-elk LR
+      L["Loki"]
+      PT["Promtail"]
+      SL["Syslog-ng"]
+      PT-->L
+      SL-->PT
+      subgraph ACI
+        S["Switches"]
+        APIC["APIC"]
+      end
+      V{Ver >= 6.1}
+      S--"Syslog"-->V
+      APIC--"Syslog"-->V
+      V -->|Yes| PT
+      V -->|No| SL
+```
+
+## Config Explorer:
+
+ACI-Monitoring-Stack will generate a Config Snapshot every 15min (By default) and automatically load it into Memgraph.
+Backup2Graph uses ACI API Call to:
+- Create a new snapshot policy
+- Trigger a snapshot
+- Delete the snapshot policy and snapshot (once transferred out of the APIC)
+
+and then uses `scp` to copy it over for processing. Once the Snapshot is copied the APIC config is cleaned up
+
+```mermaid
+    flowchart-elk RL
+      U["User"]
+      G["Grafana"]
+      A["APIC"]
+      B2G["Backup2Graph"]
+      MG["Memgraph"]
+      A--"Backup"-->B2G
+      B2G--"Push"-->MG
+      MG--"Cypher Queries"-->G
+      G-->U
+```
+
+## Data Visualization
+
+The Data Visualization is handled by `Grafana`, an open-source analytics and monitoring platform that allows users to visualize, query, and analyze data from various sources through customizable and interactive dashboards. It supports a wide range of data sources, including `Prometheus` and `Loki` enabling users to create real-time visualizations, alerts, and reports to monitor system performance and gain actionable insights.
+
+```mermaid
+    flowchart-elk RL
+      G["Grafana"]
+      L["Loki"]
+      P[("Prometheus")]
+      U["User"]
+
+      P--"PromQL"-->G
+      L--"LogQL"-->G
+      G-->U
+```
+## Alerting
+
+`Alertmanager` is a component of the `Prometheus` ecosystem designed to handle alerts generated by `Prometheus`. It manages the entire lifecycle of alerts, including deduplication, grouping, silencing, and routing notifications to various communication channels like email, `Webex`, `Slack`, and others, ensuring that alerts are delivered to the right people in a timely and organized manner.
+
+In the ACI Monitoring Stack both `Prometheus` and `Loki` are configured with alerting rules.
+```mermaid
+flowchart-elk LR
+  L["Loki"]
+  P["Prometheus"]
+  AM["Alertmanager"]
+  N["Notifications (Mail/Webex etc...)"]
+  L --> AM
+  P --> AM 
+  AM --> N
+```
+
+[Back](README.md)

docs/demo-environment.md

@@ -31,10 +31,13 @@ The stack is pre-provisioned with the following Dashboards. Feel free to explore
   - [Nodes Interfaces](#nodes-interfaces)
   - [Power Usage](#power-usage)
   - [Routing Protocols](#routing-protocols)
-  - [Vlans](#vlans)
 - [Loki backed Dashboards](#loki-backed-dashboards)
   - [Contract Drops Logs](#contract-drops-logs)
-
+- [Config Export Dashboards](#config-export-dashboards)
+  - [Contract Explorer](#contract-explorer)
+  - [Fabric Policies - Port Group](#fabric-policies-port-group)
+  - [Missing Targets](#missing-targets)
+  - [Vlans](#vlans)
 
 ## Prometheus backed Dashboards
 
@@ -116,10 +119,6 @@ This dashboard contains the following graphs:
 - BGP Advertised/Received Paths: For every BGP peering we display the number of paths received/advertised
 - BGP Accepted Paths: Time series graph of **received** BGP prefixes
 
-### Vlans
-
-Display the APIC config for VLAN Pools and VMM Custom Trunk Ports in filterable tables. 
-
 ## Loki backed Dashboards
 
 These dashboards are using `Loki` as data source meaning the data we are visualizing came from an ACI Syslog Message
@@ -128,4 +127,34 @@ These dashboards are using `Loki` as data source meaning the data we are visuali
 
 This dashboard parses the logs received by the switches and extract infos on the Contract Drop Logs. This requires a specific [config](syslog.md) on ACI and is limited to 500 Messages/s per switch
 
+## Config Export Dashboards
+These dashboard are based on data extracted from ACI Config Snapshot and converted in a Graph Database.
+
+### Contract Explorer
+
+This dashboard allows the user to select a contract and will display how a contract is deployed and what EPG/ESGs are providing or consuming it.
+
+<img src=images/contract-explorer.png width="1200">
+
+### Fabric Policies - Port Group
+
+This dashboard displays detailed information about a port group allowing the user to understand the mappings of:
+
+- VLANs
+- Domains
+- AAEP
+- Leaves and ports 
+
+<img src=images/port-group.png width="1200">
+
+### Missing Targets
+
+Detects and Show missing targets. This is still a bit of a work in progress and should be improved a bit!
+![alt text](images/missing-targets.png)
+
+### Vlans
+
+Display the APIC config for VLAN Pools and VMM Custom Trunk Ports in filterable tables. 
+![alt text](images/vlans.png)
+
 [Next - Lab1](labs/lab1.md)

docs/images/contract-explorer.png

@@ -0,0 +1,50 @@
+# Overview 
+
+All the dashboards that are tagged as `cisco-aci-config` are generated by creating a backup of the ACI confing and importint it into a graph database.
+
+A graph database is a type of database designed to represent and store data as a network of interconnected nodes (entities) and edges (relationships). Unlike traditional relational databases that use tables, graph databases use graph structures to model relationships between data, making them highly efficient for querying and analyzing complex, interconnected data. Each node represents an entity (e.g., a person, product, or location), while edges define relationships (e.g., "friend of," "purchased," or "located at").
+
+This works great to represent the ACI Configuration and allows us to create custom dashboards by using the `Cypher` language. 
+
+Cypher is a query language specifically designed for working with graph databases. It is declarative, meaning you describe what you want to retrieve or manipulate in the graph, and the database engine determines the best way to execute the query. Cypher is similar in concept to SQL for relational databases but is optimized for graph structures, enabling intuitive and powerful querying of nodes (entities), relationships (edges), and their properties.
+
+Cypher uses a pattern-matching syntax that resembles ASCII art, making it easy to visualize and query graphs. For example, (a)-[r]->(b) represents a node a connected to node b by a relationship r. You can use Cypher to perform a variety of graph operations, such as finding shortest paths, traversing relationships, filtering based on properties, and creating or modifying nodes and edges.
+
+Feel free to explore the pre-existing dashboard once you are done if you want to experiment head over to:
+
+You can find `Explore` in the left panel of the Grafana UI and from the Drop Down Select `memgraph`
+![alt text](images/lab2/explore.png)
+
+Now let's try writing a simple query:
+
+```sql
+MATCH (t:fvTenant)-[r]-(vrf:fvCtx) 
+WHERE t.fabric="site3"
+return *
+```
+
+This will return a mapping of Tenants to VRF. Try now to take a look at the `Contract Explorer` dashboard and edit it. You will see that the cypher query is a bit more complex:
+
+```sql
+MATCH (provider)-[r1:fvRsProv|vzRsAnyToProv]-(contract:vzBrCP)-[r2:fvRsCons|vzRsAnyToCons]-(consumer)
+WHERE  contract.dn="uni/tn-$tenant/brc-$contract" and contract.fabric='$fabric'
+
+RETURN provider.dn as ProviderDN, consumer.dn as ConsumerDN
+```
+
+1. MATCH: The query is looking for a specific structure (or pattern) in the graph.
+2. Nodes:
+    - (provider): A node representing the provider (this could be any entity or object, depending on the graph's context). I do like this as this can be a EPG/ESG or a VRF
+    - (contract:vzBrCP): A node representing a contract, specifically an ACI Class of type vzBrCP 
+    -  (consumer): A node representing the consumer (another entity or object). I do like this as this can be a EPG/ESG or a VRF
+3. Relationships:
+   - [r1:fvRsProv|vzRsAnyToProv]: There is a relationship between the `provider` and the `contract`, which can be of type fvRsProv or vzRsAnyToProv.
+   - [r2:fvRsCons|vzRsAnyToCons]: There is a relationship between the `contract` and the `consumer`, which can be of type fvRsCons or vzRsAnyToCons.
+4. Pattern:
+    - The query is looking for a provider node that is connected to a contract node via one of the specified relationships (fvRsProv or vzRsAnyToProv).
+    - Then, it looks for a consumer node that is also connected to the same contract node via one of the specified relationships (fvRsCons or vzRsAnyToCons).
+
+5. WHERE: It simply filter the result by fabric and contract name that you can select from the grafana dashboard.
+6. RETURN: Instead of returning everything we return only the Distinguisher names of the ACI Objects. 
+
+If you want to challenge yourself you can take a look at the `Fabric Policies - Port Group` dashboard query.