carverauto/serviceradar

Fork 0

doc re-org #2338

Merged

mfreeman451 merged 1 commit from refs/pull/2338/head into main

2025-10-19 02:08:45 +00:00

mfreeman451 commented

2025-10-19 02:08:21 +00:00

(Migrated from github.com)

Owner

Imported from GitHub pull request.

Original GitHub pull request: #1800
Original author: @mfreeman451
Original URL: https://github.com/carverauto/serviceradar/pull/1800
Original created: 2025-10-19T02:08:21Z
Original updated: 2025-10-19T02:09:46Z
Original head: carverauto/serviceradar:docs/cleanup_and_reindex
Original base: main
Original merged: 2025-10-19T02:08:45Z by @mfreeman451

PR Type

Documentation

Description

Reorganized documentation structure with comprehensive sidebar navigation
Added 12 new integration and deployment guides covering SNMP, Syslog, NetFlow, OTEL, Armis, and NetBox
Created foundational docs for cluster architecture, discovery, quickstart, and troubleshooting
Replaced autogenerated sidebar with manually curated hierarchical categories for improved navigation

Diagram Walkthrough

flowchart LR
  A["Sidebar Config"] -->|"Replaced autogenerated"| B["Manual Hierarchy"]
  B --> C["Overview Category"]
  B --> D["Get Started Category"]
  B --> E["Get Data In Category"]
  B --> F["Integrations Category"]
  B --> G["Deployment Category"]
  B --> H["Troubleshooting Category"]
  C --> C1["intro, architecture, cluster"]
  D --> D1["quickstart, guides, showcases, howtos"]
  E --> E1["snmp, syslog, netflow, otel, discovery"]
  F --> F1["armis, netbox"]
  G --> G1["installation, docker, kubernetes"]
  H --> H1["troubleshooting-guide, agents, runbooks"]

File Walkthrough

Relevant files

Documentation

11 files

sidebars.ts `Replaced autogenerated sidebar with manual hierarchical structure`	+83/-10
armis.md `New Armis integration guide with configuration and troubleshooting`	+51/-0
cluster.md `New cluster architecture and component overview documentation`	+40/-0
discovery.md `New discovery jobs and network scanning guide`	+31/-0
netbox.md `New NetBox integration guide with configuration steps`	+63/-0
netflow.md `New NetFlow ingest and collector configuration guide`	+31/-0
otel.md `New OpenTelemetry ingest guide with endpoint configuration`	+36/-0
quickstart.md `New quickstart guide with six-step onboarding path`	+49/-0
snmp.md `New SNMP ingest guide with polling and trap configuration`	+39/-0
syslog.md `New Syslog ingest guide with gateway and parsing setup`	+31/-0
troubleshooting-guide.md `New comprehensive troubleshooting guide with diagnostic steps`	+67/-0

Imported from GitHub pull request. Original GitHub pull request: #1800 Original author: @mfreeman451 Original URL: https://github.com/carverauto/serviceradar/pull/1800 Original created: 2025-10-19T02:08:21Z Original updated: 2025-10-19T02:09:46Z Original head: carverauto/serviceradar:docs/cleanup_and_reindex Original base: main Original merged: 2025-10-19T02:08:45Z by @mfreeman451 --- ### **PR Type** Documentation ___ ### **Description** - Reorganized documentation structure with comprehensive sidebar navigation - Added 12 new integration and deployment guides covering SNMP, Syslog, NetFlow, OTEL, Armis, and NetBox - Created foundational docs for cluster architecture, discovery, quickstart, and troubleshooting - Replaced autogenerated sidebar with manually curated hierarchical categories for improved navigation ___ ### Diagram Walkthrough ```mermaid flowchart LR A["Sidebar Config"] -->|"Replaced autogenerated"| B["Manual Hierarchy"] B --> C["Overview Category"] B --> D["Get Started Category"] B --> E["Get Data In Category"] B --> F["Integrations Category"] B --> G["Deployment Category"] B --> H["Troubleshooting Category"] C --> C1["intro, architecture, cluster"] D --> D1["quickstart, guides, showcases, howtos"] E --> E1["snmp, syslog, netflow, otel, discovery"] F --> F1["armis, netbox"] G --> G1["installation, docker, kubernetes"] H --> H1["troubleshooting-guide, agents, runbooks"] ``` <details> <summary><h3> File Walkthrough</h3></summary> <table><thead><tr><th></th><th align="left">Relevant files</th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td><details><summary>11 files</summary><table> <tr> <td><strong>sidebars.ts</strong><dd><code>Replaced autogenerated sidebar with manual hierarchical structure</code></dd></td> <td><a href="https://github.com/carverauto/serviceradar/pull/1800/files#diff-6e908f6e4016ad389cfb93ce7a47df677247c0f9d17c3589710592e8cf9527e0">+83/-10</a>  </td> </tr> <tr> <td><strong>armis.md</strong><dd><code>New Armis integration guide with configuration and troubleshooting</code></dd></td> <td><a href="https://github.com/carverauto/serviceradar/pull/1800/files#diff-3e5c728550851ae1cfb8754eb8a1566d8084ebc58646c73f7c29ac6f7d60adbf">+51/-0</a>    </td> </tr> <tr> <td><strong>cluster.md</strong><dd><code>New cluster architecture and component overview documentation</code></dd></td> <td><a href="https://github.com/carverauto/serviceradar/pull/1800/files#diff-0d2e32a530d31d08b311213cd036c14e611d2f9a31e9cbcaa97f02b53edeeb44">+40/-0</a>    </td> </tr> <tr> <td><strong>discovery.md</strong><dd><code>New discovery jobs and network scanning guide</code>                        </dd></td> <td><a href="https://github.com/carverauto/serviceradar/pull/1800/files#diff-a7f02a003a0e9aaf09d6aa072689ca8ad8b7b298ee014c6ffb878d2a5ecbab28">+31/-0</a>    </td> </tr> <tr> <td><strong>netbox.md</strong><dd><code>New NetBox integration guide with configuration steps</code>        </dd></td> <td><a href="https://github.com/carverauto/serviceradar/pull/1800/files#diff-ee0f0a76b85416a7c6e086eca04b7991c176075816b51f442ddb94ea6506dc68">+63/-0</a>    </td> </tr> <tr> <td><strong>netflow.md</strong><dd><code>New NetFlow ingest and collector configuration guide</code>          </dd></td> <td><a href="https://github.com/carverauto/serviceradar/pull/1800/files#diff-a64260e87bce20ed3bd93c7b64dac6ff175cdc7c67071276601aa9f6d370d634">+31/-0</a>    </td> </tr> <tr> <td><strong>otel.md</strong><dd><code>New OpenTelemetry ingest guide with endpoint configuration</code></dd></td> <td><a href="https://github.com/carverauto/serviceradar/pull/1800/files#diff-498eac46d1b44ca23346a9ef5edc4f38030fe37ce7313e691a0644e9deb381f4">+36/-0</a>    </td> </tr> <tr> <td><strong>quickstart.md</strong><dd><code>New quickstart guide with six-step onboarding path</code>              </dd></td> <td><a href="https://github.com/carverauto/serviceradar/pull/1800/files#diff-db23839e9fa71374d53983730e318028367dff34e8c817cd1e8acfec09624fe8">+49/-0</a>    </td> </tr> <tr> <td><strong>snmp.md</strong><dd><code>New SNMP ingest guide with polling and trap configuration</code></dd></td> <td><a href="https://github.com/carverauto/serviceradar/pull/1800/files#diff-5d2a72888517a4c731287280253a29cedbcbe595f1ce57c2fa14aef37c62595a">+39/-0</a>    </td> </tr> <tr> <td><strong>syslog.md</strong><dd><code>New Syslog ingest guide with gateway and parsing setup</code>      </dd></td> <td><a href="https://github.com/carverauto/serviceradar/pull/1800/files#diff-8efe898141f64a74b80133318b56ed95d03703ac95b47cebc95978b7ef761a4a">+31/-0</a>    </td> </tr> <tr> <td><strong>troubleshooting-guide.md</strong><dd><code>New comprehensive troubleshooting guide with diagnostic steps</code></dd></td> <td><a href="https://github.com/carverauto/serviceradar/pull/1800/files#diff-343b87dd0b430b3f99b16d32200c353bb6e3d7bbb185da3c1b3effc3a03e7f2a">+67/-0</a>    </td> </tr> </table></details></td></tr></tr></tbody></table> </details> ___

qodo-code-review[bot] commented

2025-10-19 02:08:53 +00:00

(Migrated from github.com)

Author

Owner

Imported GitHub PR comment.

Original author: @qodo-code-review[bot]
Original URL: https://github.com/carverauto/serviceradar/pull/1800#issuecomment-3419139604
Original created: 2025-10-19T02:08:53Z

You are nearing your monthly Qodo Merge usage quota. For more information, please visit here.

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided `- [ ] Create ticket/issue <!-- /create_ticket --create_ticket=true --> </details></td></tr>`
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
⚪	No custom compliance provided Follow the guide to enable custom compliance check.

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

Imported GitHub PR comment. Original author: @qodo-code-review[bot] Original URL: https://github.com/carverauto/serviceradar/pull/1800#issuecomment-3419139604 Original created: 2025-10-19T02:08:53Z --- _You are nearing your monthly Qodo Merge usage quota. For more information, please visit [here](https://qodo-merge-docs.qodo.ai/installation/qodo_merge/#cloud-users)._ ## PR Compliance Guide 🔍  Below is a summary of compliance checks for this PR:<br> <table><tbody><tr><td colspan='2'><strong>Security Compliance</strong></td></tr> <tr><td>🟢</td><td><details><summary><strong>No security concerns identified</strong></summary> No security vulnerabilities detected by AI analysis. Human verification advised for critical code. </details></td></tr> <tr><td colspan='2'><strong>Ticket Compliance</strong></td></tr> <tr><td>⚪</td><td><details><summary>🎫 <strong>No ticket provided </summary></strong> - [ ] Create ticket/issue  </details></td></tr> <tr><td colspan='2'><strong>Codebase Duplication Compliance</strong></td></tr> <tr><td>⚪</td><td><details><summary><strong>Codebase context is not defined </strong></summary> Follow the <a href='https://qodo-merge-docs.qodo.ai/core-abilities/rag_context_enrichment/'>guide</a> to enable codebase context checks. </details></td></tr> <tr><td colspan='2'><strong>Custom Compliance</strong></td></tr> <tr><td>⚪</td><td><details><summary><strong>No custom compliance provided</strong></summary> Follow the <a href='https://qodo-merge-docs.qodo.ai/tools/compliance/'>guide</a> to enable custom compliance check. </details></td></tr> <tr><td align="center" colspan="2">   </td></tr></tbody></table> <details><summary>Compliance status legend</summary> 🟢 - Fully Compliant<br> 🟡 - Partial Compliant<br> 🔴 - Not Compliant<br> ⚪ - Requires Further Human Verification<br> 🏷️ - Compliance label<br> </details>

qodo-code-review[bot] commented

2025-10-19 02:09:46 +00:00

(Migrated from github.com)

Author

Owner

Imported GitHub PR comment.

Original author: @qodo-code-review[bot]
Original URL: https://github.com/carverauto/serviceradar/pull/1800#issuecomment-3419140011
Original created: 2025-10-19T02:09:46Z

You are nearing your monthly Qodo Merge usage quota. For more information, please visit here.

PR Code Suggestions ✨

Explore these optional code suggestions:

Category Suggestion Impact

High-level

Category	Suggestion	Impact
High-level	Consolidate configuration into a single source The documentation includes configuration snippets in multiple guides. To improve maintainability and reduce user confusion, create a central configuration reference page and have individual guides link to it. Examples: docs/docs/armis.md [17-30] 1. Populate the Sync config with the Armis connector block: ```json { "integrations": { "armis": { "api_url": "https://<tenant>.armis.com/api/v1", "client_id": "${kv:secrets/armis/client_id}", "client_secret": "${kv:secrets/armis/client_secret}", "page_size": 500 ... (clipped 4 lines) docs/docs/netbox.md [17-34] 1. Add the NetBox block to your Sync configuration: ```json { "integrations": { "netbox": { "type": "netbox", "endpoint": "https://netbox.example.com/api", "prefix": "netbox/", "credentials": { ... (clipped 8 lines) Solution Walkthrough: Before: // In docs/docs/armis.md # Armis Integration ... ## Enabling the Integration 1. Populate the Sync config with the Armis connector block: ```json { "integrations": { "armis": { ... } } } // In docs/docs/netbox.md NetBox Integration ... Configuration Steps Add the NetBox block to your Sync configuration: `{ "integrations": { "netbox": { ... } } }` #### After: ```markdown // In docs/docs/configuration-reference.md (new file) # Configuration Reference ## Sync Service The `integrations` block supports the following connectors: ```json { "integrations": { "armis": { ... }, "netbox": { ... } } } // In docs/docs/armis.md Armis Integration ... Enabling the Integration Add the `armis` block to your Sync configuration. See the Configuration Reference for details. // In docs/docs/netbox.md NetBox Integration ... Configuration Steps Add the `netbox` block to your Sync configuration. See the Configuration Reference for details. <details><summary>Suggestion importance[1-10]: 7</summary> __ Why: The suggestion correctly identifies fragmented configuration snippets across new documentation files and proposes a centralized approach, which significantly improves documentation maintainability and user experience. </details></details></td><td align=center>Medium </td></tr><tr><td rowspan=1>Possible issue</td> <td> <details><summary>Correct the placement of a configuration option</summary> ___ Move the <code>expand_subnets</code> option out of the <code>credentials</code> object in the NetBox <br>configuration example to align with the "Advanced Options" table in the same <br>document. [docs/docs/netbox.md [26-30]](https://github.com/carverauto/serviceradar/pull/1800/files#diff-ee0f0a76b85416a7c6e086eca04b7991c176075816b51f442ddb94ea6506dc68R26-R30) ```diff "credentials": { - "api_token": "${kv:secrets/netbox/api_token}", - "expand_subnets": "true" + "api_token": "${kv:secrets/netbox/api_token}" }, +"expand_subnets": "true", "partition": "default" Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies an inconsistency in the `netbox.md` documentation, where the `expand_subnets` option is misplaced in the JSON configuration example, which would cause user confusion and incorrect behavior.	Low
More

Consolidate configuration into a single source

The documentation includes configuration snippets in multiple guides. To improve
maintainability and reduce user confusion, create a central configuration
reference page and have individual guides link to it.

Examples:

docs/docs/armis.md [17-30]

1. Populate the Sync config with the Armis connector block:

   ```json
   {
     "integrations": {
       "armis": {
         "api_url": "https://<tenant>.armis.com/api/v1",
         "client_id": "${kv:secrets/armis/client_id}",
         "client_secret": "${kv:secrets/armis/client_secret}",
         "page_size": 500

 ... (clipped 4 lines)

docs/docs/netbox.md [17-34]

1. Add the NetBox block to your Sync configuration:

   ```json
   {
     "integrations": {
       "netbox": {
         "type": "netbox",
         "endpoint": "https://netbox.example.com/api",
         "prefix": "netbox/",
         "credentials": {

 ... (clipped 8 lines)

Solution Walkthrough:

Before:

// In docs/docs/armis.md
# Armis Integration
...
## Enabling the Integration
1. Populate the Sync config with the Armis connector block:
   ```json
   {
     "integrations": {
       "armis": { ... }
     }
   }

// In docs/docs/netbox.md

NetBox Integration

...

Configuration Steps

Add the NetBox block to your Sync configuration:

{
  "integrations": {
    "netbox": { ... }
  }
}




#### After:
```markdown
// In docs/docs/configuration-reference.md (new file)
# Configuration Reference
## Sync Service
The `integrations` block supports the following connectors:
```json
{
  "integrations": {
    "armis": { ... },
    "netbox": { ... }
  }
}

// In docs/docs/armis.md

Armis Integration

...

Enabling the Integration

Add the armis block to your Sync configuration.
See the Configuration Reference for details.

// In docs/docs/netbox.md

NetBox Integration

...

Configuration Steps

Add the netbox block to your Sync configuration.
See the Configuration Reference for details.





<details><summary>Suggestion importance[1-10]: 7</summary>

__

Why: The suggestion correctly identifies fragmented configuration snippets across new documentation files and proposes a centralized approach, which significantly improves documentation maintainability and user experience.


</details></details></td><td align=center>Medium

</td></tr><tr><td rowspan=1>Possible issue</td>
<td>



<details><summary>Correct the placement of a configuration option</summary>

___

**Move the <code>expand_subnets</code> option out of the <code>credentials</code> object in the NetBox <br>configuration example to align with the "Advanced Options" table in the same <br>document.**

[docs/docs/netbox.md [26-30]](https://github.com/carverauto/serviceradar/pull/1800/files#diff-ee0f0a76b85416a7c6e086eca04b7991c176075816b51f442ddb94ea6506dc68R26-R30)

```diff
 "credentials": {
-  "api_token": "${kv:secrets/netbox/api_token}",
-  "expand_subnets": "true"
+  "api_token": "${kv:secrets/netbox/api_token}"
 },
+"expand_subnets": "true",
 "partition": "default"

Apply / Chat

Suggestion importance[1-10]: 6

Why: The suggestion correctly identifies an inconsistency in the netbox.md documentation, where the expand_subnets option is misplaced in the JSON configuration example, which would cause user confusion and incorrect behavior.

Low

Imported GitHub PR comment. Original author: @qodo-code-review[bot] Original URL: https://github.com/carverauto/serviceradar/pull/1800#issuecomment-3419140011 Original created: 2025-10-19T02:09:46Z --- _You are nearing your monthly Qodo Merge usage quota. For more information, please visit [here](https://qodo-merge-docs.qodo.ai/installation/qodo_merge/#cloud-users)._ ## PR Code Suggestions ✨  Explore these optional code suggestions: <table><thead><tr><td><strong>Category</strong></td><td align=left><strong>Suggestion                                                                                                                                    </strong></td><td align=center><strong>Impact</strong></td></tr><tbody><tr><td rowspan=1>High-level</td> <td> <details><summary>Consolidate configuration into a single source</summary> ___ **The documentation includes configuration snippets in multiple guides. To improve <br>maintainability and reduce user confusion, create a central configuration <br>reference page and have individual guides link to it.** ### Examples: <details> <summary> <a href="https://github.com/carverauto/serviceradar/pull/1800/files#diff-3e5c728550851ae1cfb8754eb8a1566d8084ebc58646c73f7c29ac6f7d60adbfR17-R30">docs/docs/armis.md [17-30]</a> </summary> ```markdown 1. Populate the Sync config with the Armis connector block: ```json { "integrations": { "armis": { "api_url": "https://<tenant>.armis.com/api/v1", "client_id": "${kv:secrets/armis/client_id}", "client_secret": "${kv:secrets/armis/client_secret}", "page_size": 500 ... (clipped 4 lines) ``` </details> <details> <summary> <a href="https://github.com/carverauto/serviceradar/pull/1800/files#diff-ee0f0a76b85416a7c6e086eca04b7991c176075816b51f442ddb94ea6506dc68R17-R34">docs/docs/netbox.md [17-34]</a> </summary> ```markdown 1. Add the NetBox block to your Sync configuration: ```json { "integrations": { "netbox": { "type": "netbox", "endpoint": "https://netbox.example.com/api", "prefix": "netbox/", "credentials": { ... (clipped 8 lines) ``` </details> ### Solution Walkthrough: #### Before: ```markdown // In docs/docs/armis.md # Armis Integration ... ## Enabling the Integration 1. Populate the Sync config with the Armis connector block: ```json { "integrations": { "armis": { ... } } } ``` // In docs/docs/netbox.md # NetBox Integration ... ## Configuration Steps 1. Add the NetBox block to your Sync configuration: ```json { "integrations": { "netbox": { ... } } } ``` ``` #### After: ```markdown // In docs/docs/configuration-reference.md (new file) # Configuration Reference ## Sync Service The `integrations` block supports the following connectors: ```json { "integrations": { "armis": { ... }, "netbox": { ... } } } ``` // In docs/docs/armis.md # Armis Integration ... ## Enabling the Integration 1. Add the `armis` block to your Sync configuration. See the [Configuration Reference](./configuration-reference.md#sync-service) for details. // In docs/docs/netbox.md # NetBox Integration ... ## Configuration Steps 1. Add the `netbox` block to your Sync configuration. See the [Configuration Reference](./configuration-reference.md#sync-service) for details. ``` <details><summary>Suggestion importance[1-10]: 7</summary> __ Why: The suggestion correctly identifies fragmented configuration snippets across new documentation files and proposes a centralized approach, which significantly improves documentation maintainability and user experience. </details></details></td><td align=center>Medium </td></tr><tr><td rowspan=1>Possible issue</td> <td> <details><summary>Correct the placement of a configuration option</summary> ___ **Move the <code>expand_subnets</code> option out of the <code>credentials</code> object in the NetBox <br>configuration example to align with the "Advanced Options" table in the same <br>document.** [docs/docs/netbox.md [26-30]](https://github.com/carverauto/serviceradar/pull/1800/files#diff-ee0f0a76b85416a7c6e086eca04b7991c176075816b51f442ddb94ea6506dc68R26-R30) ```diff "credentials": { - "api_token": "${kv:secrets/netbox/api_token}", - "expand_subnets": "true" + "api_token": "${kv:secrets/netbox/api_token}" }, +"expand_subnets": "true", "partition": "default" ``` - [ ] **Apply / Chat**  <details><summary>Suggestion importance[1-10]: 6</summary> __ Why: The suggestion correctly identifies an inconsistency in the `netbox.md` documentation, where the `expand_subnets` option is misplaced in the JSON configuration example, which would cause user confusion and incorrect behavior. </details></details></td><td align=center>Low </td></tr> <tr><td align="center" colspan="2"> - [ ] More  </td><td></td></tr></tbody></table>