docs: add Network Insights, Network Map, API Tokens, REST API, and GraphQL API sections to help page
This commit is contained in:
parent
42f7f41584
commit
596b404baf
1 changed files with 273 additions and 0 deletions
|
|
@ -283,6 +283,81 @@ defmodule ToweropsWeb.HelpLive.Index do
|
|||
Graphs & Live Polling
|
||||
</.link>
|
||||
</li>
|
||||
<li>
|
||||
<.link
|
||||
patch={~p"/help?section=insights"}
|
||||
class={[
|
||||
"block px-3 py-2 rounded-md text-sm font-medium transition-colors",
|
||||
if @active_section == "insights" do
|
||||
"bg-blue-50 text-blue-700 dark:bg-blue-900/50 dark:text-blue-300"
|
||||
else
|
||||
"text-gray-700 hover:bg-gray-50 dark:text-gray-300 dark:hover:bg-gray-800"
|
||||
end
|
||||
]}
|
||||
>
|
||||
Network Insights
|
||||
</.link>
|
||||
</li>
|
||||
<li>
|
||||
<.link
|
||||
patch={~p"/help?section=network-map"}
|
||||
class={[
|
||||
"block px-3 py-2 rounded-md text-sm font-medium transition-colors",
|
||||
if @active_section == "network-map" do
|
||||
"bg-blue-50 text-blue-700 dark:bg-blue-900/50 dark:text-blue-300"
|
||||
else
|
||||
"text-gray-700 hover:bg-gray-50 dark:text-gray-300 dark:hover:bg-gray-800"
|
||||
end
|
||||
]}
|
||||
>
|
||||
Network Map
|
||||
</.link>
|
||||
</li>
|
||||
<li>
|
||||
<.link
|
||||
patch={~p"/help?section=api-tokens"}
|
||||
class={[
|
||||
"block px-3 py-2 rounded-md text-sm font-medium transition-colors",
|
||||
if @active_section == "api-tokens" do
|
||||
"bg-blue-50 text-blue-700 dark:bg-blue-900/50 dark:text-blue-300"
|
||||
else
|
||||
"text-gray-700 hover:bg-gray-50 dark:text-gray-300 dark:hover:bg-gray-800"
|
||||
end
|
||||
]}
|
||||
>
|
||||
API Tokens
|
||||
</.link>
|
||||
</li>
|
||||
<li>
|
||||
<.link
|
||||
patch={~p"/help?section=rest-api"}
|
||||
class={[
|
||||
"block px-3 py-2 rounded-md text-sm font-medium transition-colors",
|
||||
if @active_section == "rest-api" do
|
||||
"bg-blue-50 text-blue-700 dark:bg-blue-900/50 dark:text-blue-300"
|
||||
else
|
||||
"text-gray-700 hover:bg-gray-50 dark:text-gray-300 dark:hover:bg-gray-800"
|
||||
end
|
||||
]}
|
||||
>
|
||||
REST API
|
||||
</.link>
|
||||
</li>
|
||||
<li>
|
||||
<.link
|
||||
patch={~p"/help?section=graphql-api"}
|
||||
class={[
|
||||
"block px-3 py-2 rounded-md text-sm font-medium transition-colors",
|
||||
if @active_section == "graphql-api" do
|
||||
"bg-blue-50 text-blue-700 dark:bg-blue-900/50 dark:text-blue-300"
|
||||
else
|
||||
"text-gray-700 hover:bg-gray-50 dark:text-gray-300 dark:hover:bg-gray-800"
|
||||
end
|
||||
]}
|
||||
>
|
||||
GraphQL API
|
||||
</.link>
|
||||
</li>
|
||||
</ul>
|
||||
</nav>
|
||||
</div>
|
||||
|
|
@ -2237,6 +2312,204 @@ defmodule ToweropsWeb.HelpLive.Index do
|
|||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<% "insights" -> %>
|
||||
<div class="p-6">
|
||||
<h2 class="text-xl font-bold text-gray-900 dark:text-white mb-4">
|
||||
Network Insights
|
||||
</h2>
|
||||
<p class="text-gray-600 dark:text-gray-400 mb-4">
|
||||
Network Insights provides proactive observations about your network health, gathered automatically from all connected data sources.
|
||||
</p>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">How It Works</h3>
|
||||
<p class="text-gray-600 dark:text-gray-400 mb-4">
|
||||
Towerops continuously analyzes data from SNMP polling, Preseem, Gaiia, and other integrations to surface actionable findings. Insights are categorized by source, urgency, and type so you can focus on what matters.
|
||||
</p>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Insight Types</h3>
|
||||
<ul class="list-disc list-inside text-gray-600 dark:text-gray-400 space-y-2 mb-4">
|
||||
<li><strong>Reconciliation Findings</strong> — Devices that exist in Towerops but not in Gaiia (or vice versa), data mismatches between systems</li>
|
||||
<li><strong>Performance Anomalies</strong> — Devices with unusual metric patterns detected by Preseem or SNMP baselines</li>
|
||||
<li><strong>Configuration Drift</strong> — Detected changes to device configurations that may affect performance</li>
|
||||
<li><strong>Capacity Warnings</strong> — Access points or links approaching utilization thresholds</li>
|
||||
</ul>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Filtering & Management</h3>
|
||||
<p class="text-gray-600 dark:text-gray-400 mb-4">
|
||||
Use the filter bar to narrow insights by status (active/dismissed), source (Preseem, Gaiia, SNMP, system), and urgency level. Each insight shows affected devices as clickable links so you can drill directly into the device detail page.
|
||||
</p>
|
||||
<p class="text-gray-600 dark:text-gray-400 mb-4">
|
||||
Dismiss insights you've reviewed to keep the active list clean. Bulk actions let you select multiple insights at once.
|
||||
</p>
|
||||
|
||||
<div class="mt-6 rounded-lg bg-blue-50 dark:bg-blue-900/20 p-4">
|
||||
<p class="text-sm text-blue-700 dark:text-blue-300">
|
||||
<strong>Tip:</strong> Insights run on a nightly schedule. Connect your Gaiia and Preseem integrations in
|
||||
<.link navigate={~p"/help?section=integrations"} class="underline">Organization Settings</.link>
|
||||
to get the most comprehensive insights.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<% "network-map" -> %>
|
||||
<div class="p-6">
|
||||
<h2 class="text-xl font-bold text-gray-900 dark:text-white mb-4">
|
||||
Network Map
|
||||
</h2>
|
||||
<p class="text-gray-600 dark:text-gray-400 mb-4">
|
||||
The Network Map provides a geographic view of your sites on an interactive map. Sites with latitude and longitude coordinates are displayed as markers that you can click to view details.
|
||||
</p>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Adding Location Data</h3>
|
||||
<p class="text-gray-600 dark:text-gray-400 mb-4">
|
||||
Each site can have an address and/or latitude/longitude coordinates. You can set these in two ways:
|
||||
</p>
|
||||
<ul class="list-disc list-inside text-gray-600 dark:text-gray-400 space-y-2 mb-4">
|
||||
<li><strong>Manual entry</strong> — Enter latitude and longitude directly in the site edit form</li>
|
||||
<li><strong>Geocoding</strong> — Enter a street address and click "Geocode" to automatically look up the coordinates using Google Maps</li>
|
||||
</ul>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Geocoding Setup</h3>
|
||||
<p class="text-gray-600 dark:text-gray-400 mb-4">
|
||||
Address-to-coordinate conversion requires a Google Maps Geocoding API key. Your administrator sets this as the <code class="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono dark:bg-gray-700">GOOGLE_MAPS_API_KEY</code> environment variable on the server. The map display itself uses OpenStreetMap and requires no API key.
|
||||
</p>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Map Features</h3>
|
||||
<ul class="list-disc list-inside text-gray-600 dark:text-gray-400 space-y-2 mb-4">
|
||||
<li>Interactive pan and zoom with OpenStreetMap tiles</li>
|
||||
<li>Click any site marker to see site name, device count, and a link to the site detail page</li>
|
||||
<li>Auto-fits the map to show all your sites</li>
|
||||
<li>Summary stats showing total sites, mapped sites, and total devices</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<% "api-tokens" -> %>
|
||||
<div class="p-6">
|
||||
<h2 class="text-xl font-bold text-gray-900 dark:text-white mb-4">
|
||||
API Tokens
|
||||
</h2>
|
||||
<p class="text-gray-600 dark:text-gray-400 mb-4">
|
||||
API tokens allow external applications and scripts to authenticate with the Towerops REST and GraphQL APIs. Each token is scoped to an organization and can be managed from your user settings.
|
||||
</p>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Creating a Token</h3>
|
||||
<ol class="list-decimal list-inside text-gray-600 dark:text-gray-400 space-y-2 mb-4">
|
||||
<li>Go to <strong>User Settings → API Tokens</strong></li>
|
||||
<li>Click <strong>"Create API Token"</strong></li>
|
||||
<li>Give the token a descriptive name (e.g., "Grafana Integration")</li>
|
||||
<li>Copy the token immediately — it will only be shown once</li>
|
||||
</ol>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Using a Token</h3>
|
||||
<p class="text-gray-600 dark:text-gray-400 mb-4">
|
||||
Include the token in the <code class="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono dark:bg-gray-700">Authorization</code> header:
|
||||
</p>
|
||||
<div class="rounded-lg bg-gray-900 p-4 mb-4">
|
||||
<pre class="text-sm text-green-400 overflow-x-auto"><code>Authorization: Bearer your-api-token-here</code></pre>
|
||||
</div>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Security Best Practices</h3>
|
||||
<ul class="list-disc list-inside text-gray-600 dark:text-gray-400 space-y-2 mb-4">
|
||||
<li>Create separate tokens for each integration — don't reuse tokens across services</li>
|
||||
<li>Revoke tokens you no longer need</li>
|
||||
<li>Never commit tokens to version control</li>
|
||||
<li>Store tokens in environment variables or a secrets manager</li>
|
||||
</ul>
|
||||
|
||||
<div class="mt-6 rounded-lg bg-blue-50 dark:bg-blue-900/20 p-4">
|
||||
<p class="text-sm text-blue-700 dark:text-blue-300">
|
||||
<strong>See also:</strong>
|
||||
<.link navigate={~p"/help?section=rest-api"} class="underline">REST API</.link> and
|
||||
<.link navigate={~p"/help?section=graphql-api"} class="underline">GraphQL API</.link>
|
||||
for endpoint documentation.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<% "rest-api" -> %>
|
||||
<div class="p-6">
|
||||
<h2 class="text-xl font-bold text-gray-900 dark:text-white mb-4">
|
||||
REST API
|
||||
</h2>
|
||||
<p class="text-gray-600 dark:text-gray-400 mb-4">
|
||||
The Towerops REST API provides programmatic access to your monitoring data. All endpoints are under <code class="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono dark:bg-gray-700">/api/v1/</code> and require a valid API token.
|
||||
</p>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Available Endpoints</h3>
|
||||
<ul class="list-disc list-inside text-gray-600 dark:text-gray-400 space-y-2 mb-4">
|
||||
<li><strong>Devices</strong> — List, view, create, and update monitored devices</li>
|
||||
<li><strong>Alerts</strong> — Query active and historical alerts, acknowledge, and resolve</li>
|
||||
<li><strong>Sites</strong> — Manage sites and their device assignments</li>
|
||||
<li><strong>Agents</strong> — List remote pollers and their status</li>
|
||||
<li><strong>Check Results</strong> — Query monitoring check results and metrics</li>
|
||||
<li><strong>Organization Settings</strong> — Read and update SNMP/MikroTik configuration</li>
|
||||
<li><strong>Members & Invitations</strong> — Manage organization membership</li>
|
||||
<li><strong>Integrations</strong> — Configure Preseem, Gaiia, and PagerDuty</li>
|
||||
<li><strong>Activity Feed</strong> — Recent events and changes across the organization</li>
|
||||
</ul>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Quick Example</h3>
|
||||
<div class="rounded-lg bg-gray-900 p-4 mb-4">
|
||||
<pre class="text-sm text-green-400 overflow-x-auto"><code><%= raw("curl -H \"Authorization: Bearer YOUR_TOKEN\" \\\n https://app.towerops.net/api/v1/devices") %></code></pre>
|
||||
</div>
|
||||
<p class="text-gray-600 dark:text-gray-400 mb-4">
|
||||
All responses use <code class="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono dark:bg-gray-700"><%= raw("{\"data\": ...}") %></code> format. Results are scoped to the organization associated with your API token.
|
||||
</p>
|
||||
|
||||
<div class="mt-6 rounded-lg bg-blue-50 dark:bg-blue-900/20 p-4">
|
||||
<p class="text-sm text-blue-700 dark:text-blue-300">
|
||||
<strong>Full reference:</strong>
|
||||
<a href="/docs/api" class="underline font-medium">REST API Documentation →</a>
|
||||
— complete endpoint reference with request/response examples.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<% "graphql-api" -> %>
|
||||
<div class="p-6">
|
||||
<h2 class="text-xl font-bold text-gray-900 dark:text-white mb-4">
|
||||
GraphQL API
|
||||
</h2>
|
||||
<p class="text-gray-600 dark:text-gray-400 mb-4">
|
||||
The GraphQL API lets you query exactly the data you need in a single request. The endpoint is <code class="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono dark:bg-gray-700">POST /api/graphql</code> and uses the same API token authentication as the REST API.
|
||||
</p>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Why GraphQL?</h3>
|
||||
<ul class="list-disc list-inside text-gray-600 dark:text-gray-400 space-y-2 mb-4">
|
||||
<li><strong>Fetch related data in one query</strong> — Get devices with their sites, alerts, and latest metrics in a single request</li>
|
||||
<li><strong>No over-fetching</strong> — Request only the fields you need</li>
|
||||
<li><strong>Introspection</strong> — The schema is self-documenting; use any GraphQL client to explore available types and fields</li>
|
||||
</ul>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Quick Example</h3>
|
||||
<div class="rounded-lg bg-gray-900 p-4 mb-4">
|
||||
<pre class="text-sm text-green-400 overflow-x-auto"><code><%= raw("curl -X POST https://app.towerops.net/api/graphql \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\": \"{ devices { id name ipAddress status } }\"}'") %></code></pre>
|
||||
</div>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Available Queries</h3>
|
||||
<ul class="list-disc list-inside text-gray-600 dark:text-gray-400 space-y-2 mb-4">
|
||||
<li><strong>devices</strong> — List devices with filtering and nested site/alert data</li>
|
||||
<li><strong>device(id)</strong> — Single device with full detail including sensors and interfaces</li>
|
||||
<li><strong>sites</strong> — Sites with nested device lists</li>
|
||||
<li><strong>alerts</strong> — Active and historical alerts with device context</li>
|
||||
<li><strong>agents</strong> — Remote poller agents and their assignments</li>
|
||||
</ul>
|
||||
|
||||
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mt-6 mb-3">Mutations</h3>
|
||||
<ul class="list-disc list-inside text-gray-600 dark:text-gray-400 space-y-2 mb-4">
|
||||
<li><strong>createDevice</strong> / <strong>updateDevice</strong> — Manage devices</li>
|
||||
<li><strong>acknowledgeAlert</strong> / <strong>resolveAlert</strong> — Alert lifecycle management</li>
|
||||
</ul>
|
||||
|
||||
<div class="mt-6 rounded-lg bg-blue-50 dark:bg-blue-900/20 p-4">
|
||||
<p class="text-sm text-blue-700 dark:text-blue-300">
|
||||
<strong>Full reference:</strong>
|
||||
<a href="/docs/graphql" class="underline font-medium">GraphQL API Documentation →</a>
|
||||
— complete schema reference with query examples and variable usage.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<% _ -> %>
|
||||
<div class="p-6">
|
||||
<h2 class="text-xl font-bold text-gray-900 dark:text-white mb-4">
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue