diff --git a/docs.json b/docs.json index d302d7e..e2b5411 100644 --- a/docs.json +++ b/docs.json @@ -106,7 +106,7 @@ }, { "group": "Net Diagnostics", - "pages": ["iroh-services/net-diagnostics"] + "pages": ["iroh-services/net-diagnostics/quickstart", "iroh-services/net-diagnostics/usage", "iroh-services/net-diagnostics/reports"] } ] } diff --git a/images/metrics-dashboard.png b/images/metrics-dashboard.png new file mode 100644 index 0000000..486abf1 Binary files /dev/null and b/images/metrics-dashboard.png differ diff --git a/images/metrics-direct-data-rate.png b/images/metrics-direct-data-rate.png new file mode 100644 index 0000000..6a1548e Binary files /dev/null and b/images/metrics-direct-data-rate.png differ diff --git a/images/metrics-online-endpoints.png b/images/metrics-online-endpoints.png new file mode 100644 index 0000000..a14326a Binary files /dev/null and b/images/metrics-online-endpoints.png differ diff --git a/images/metrics-relay.png b/images/metrics-relay.png new file mode 100644 index 0000000..a7a4c67 Binary files /dev/null and b/images/metrics-relay.png differ diff --git a/images/metrics-traffic-received.png b/images/metrics-traffic-received.png new file mode 100644 index 0000000..edfea09 Binary files /dev/null and b/images/metrics-traffic-received.png differ diff --git a/images/metrics-traffic-sent.png b/images/metrics-traffic-sent.png new file mode 100644 index 0000000..0ba7b6a Binary files /dev/null and b/images/metrics-traffic-sent.png differ diff --git a/iroh-services/metrics/endpoint.mdx b/iroh-services/metrics/endpoint.mdx index 544e7bb..7bfe4b2 100644 --- a/iroh-services/metrics/endpoint.mdx +++ b/iroh-services/metrics/endpoint.mdx @@ -1,9 +1,9 @@ --- title: "Endpoint Metrics" -description: "Detailed metrics at the endpoint level for Pro and Enterprise plans" +description: "Detailed metrics at the endpoint level for Enterprise plans" --- -On the pro and enterprise plan, you can get more detailed +On the enterprise plan, you can get more detailed metrics at the endpoint level. These metrics give you visibility into the behavior of individual endpoints in your network. This can help you identify performance issues or bottlenecks that may be affecting specific endpoints. @@ -24,13 +24,15 @@ network is performing optimally, leading to a better overall experience for your ## Retention and Lookback -Projects on the Pro or Enterprise plans have access to +Projects on the Enterprise plan have access to extended retention and lookback for endpoint-level metrics. This allows you to analyze historical data and identify trends over time, which can be crucial for long-term performance optimization and troubleshooting. -Please refer to the pricing page for more details on plan features -and benefits. [Contact us](mailto:support@iroh.computer) if you have any questions about upgrading your plan. +Please refer to the [pricing page](https://n0des.iroh.computer/pricing?utm_source=docs&utm_content=endpoint-metrics) for more details on plan features +and benefits. + +[Contact us](mailto:support@iroh.computer) if you have any questions about upgrading your plan. ## Glossary diff --git a/iroh-services/metrics/how-it-works.mdx b/iroh-services/metrics/how-it-works.mdx index 21e73ff..39beefc 100644 --- a/iroh-services/metrics/how-it-works.mdx +++ b/iroh-services/metrics/how-it-works.mdx @@ -7,9 +7,12 @@ description: "Understanding how Iroh Services collects and processes metrics" To enable metrics collection, simply add endpoints to your network through the Iroh Services dashboard. Metrics will be automatically collected and reported once: -1. The ssh key is uploaded to the platform. -2. The endpoint is built using the uploaded ssh key and Iroh Services platform endpoint id. -3. The endpoint sends metrics data to the project in the Iroh Services platform. + +1. The endpoint is built using the API Secret Key +2. The endpoint sends metrics data to a Cloud endpoint hosted in the Iroh Services platform. +3. The Iroh Services platform aggregates the data and makes it available in the project dashboard. +4. Iroh services deletes data on a rolling bases outside the retention window, based on your [plan](https://n0des.iroh.computer/pricing). + ## How it works @@ -22,14 +25,14 @@ key match what has been set up in your project on the Iroh Services platform. 2. Call `endpoint.online().await` before creating the Client. The endpoint must be online before the client is instantiated in order to authenticate to the platform. 3. Once authenticated, endpoints will start sending granular-level data about their behavior and connection status. -4. Every 10 seconds, the Iroh Services platform will aggregate key project-level metrics which are visible in the project dashboard. +4. Once per minute, the Iroh Services platform will aggregate key project-level metrics which are visible in the project dashboard. ## Metrics Retention Project-level metrics are retained based on your events plan. Please refer to the -pricing page for more details on plan features and benefits. +[pricing page for more details on plan features and benefits](https://n0des.iroh.computer/pricing). -Endpoint level metrics are only available on Pro and Enterprise. For projects on +Endpoint level metrics are only available on Enterprise plans. For projects on these plans, the amount of endpoint-level raw data retained is calculated on your purchased metrics package. There is a rolling lookback window for metrics retention that is based on your metrics package. [Contact diff --git a/iroh-services/metrics/index.mdx b/iroh-services/metrics/index.mdx index 0fe679e..a900147 100644 --- a/iroh-services/metrics/index.mdx +++ b/iroh-services/metrics/index.mdx @@ -15,18 +15,39 @@ All endpoint metrics are aggregated at the project level, to provide insights into overall network performance. This aggregated data helps in understanding trends and patterns without exposing individual endpoint details. -Read more about [project metrics](/iroh-services/metrics/index). +![Project metrics dashboard](/images/metrics-dashboard.png) -## Endpoint metrics +### Online Endpoints -Mmore detailed metrics are available for each endpoint added to the network. -These metrics are available at the endpoint level, so you can drill down into -specific behaviors to better understand performance issues. Projects that have -been upgraded to Enterprise plan have access to endpoint-level -metrics retention and lookback. +The number of endpoints currently online and connected to your project. This gives you a real-time view of your network's active nodes. -Read more about [endpoint metrics](/iroh-services/metrics/endpoint). +![Online endpoints metric](/images/metrics-online-endpoints.png) +### Direct Data Rate + +Direct data rate measures the amount of data being transferred directly between +endpoints in your network, without relaying through a server. A higher direct +data rate indicates better peer-to-peer connectivity and can lead to improved +performance and lower latency for your users. + +![Direct data rate metric](/images/metrics-direct-data-rate.png) + +### Traffic Sent & Received + +This metric tracks the amount of data being sent and received by your endpoints. +Monitoring traffic patterns can help you identify potential bottlenecks and +optimize network performance. + +![Traffic sent and received metric](/images/metrics-traffic-received.png) + +![Traffic sent metric](/images/metrics-traffic-sent.png) + +## Relay metrics + +If you have dedicated relays set up for your project, you can also view metrics +related to relay performance, such as number of endpoints over time and relay data transfer. + +![Relay metrics dashboard](/images/metrics-relay.png) ## Privacy diff --git a/iroh-services/net-diagnostics.mdx b/iroh-services/net-diagnostics.mdx deleted file mode 100644 index d381391..0000000 --- a/iroh-services/net-diagnostics.mdx +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: "Network Diagnostics" -description: "Diagnose user connectivity issues with remote diagnostic reporting" ---- - -Net Diagnostics lets you run network connectivity reports on your endpoints from iroh-services. Reports cover NAT type, UDP connectivity, relay latency, port mapping protocol availability, and direct addresses — everything you need to debug connection issues. You can initiate reports from iroh-services, which will reach out to configured remote nodes that have authorized diagnostics, gather details about the endpoint's connectivity context, and forward the report to your project on iroh services to assess how to help your user get the best connection they can. - -Net Diagnostics is available on the **Enterprise plan**. - -## Quick Start - -### 1. Get your API secret - -Go to your project's **Settings** page and copy the API secret. In your terminal, export it as an environment variable: - -```bash -export N0DES_API_SECRET= -``` - -### 2. Run the diagnostics client - -Clone the [iroh-n0des](https://github.com/n0-computer/iroh-n0des) repo and run the `net_diagnostics` example: - -```bash -git clone https://github.com/n0-computer/iroh-n0des.git -cd iroh-n0des -cargo run --example net_diagnostics --features net_diagnostics,client_host -``` - -Leave this terminal open. The example connects to n0des, grants the diagnostics capability to your project, and waits for incoming diagnostics requests. - -### 3. Run a diagnostic from the dashboard - -Go to your project's **Endpoints** page. You should see the example client listed as an online endpoint. Click **Run Diagnostics** to generate a report. - -The report appears on the **Net Diagnostics** page and includes: - -- **NAT Type** — No NAT, Endpoint-Independent, Endpoint-Dependent, or Unknown -- **UDP Connectivity** — IPv4 and IPv6 status with public addresses -- **NAT Mapping** — whether mapping varies by destination (symmetric NAT detection) -- **Direct Addresses** — local addresses the endpoint is listening on -- **Port Mapping** — UPnP, PCP, and NAT-PMP availability -- **Relay Latencies** — per-relay IPv4, IPv6, and HTTPS round-trip times -- **Captive Portal** — detection of captive portal interference - -## Understanding the Report - -### NAT Types - -| NAT Type | What it means | Connection quality | -|---|---|---| -| **No NAT** | Local address matches public address | Direct connections work with correct firewall config | -| **Endpoint-Independent** | One outbound UDP packet opens a port for any sender | Holepunching works reliably | -| **Endpoint-Dependent** | Only the specific destination can reply (symmetric NAT) | Connections will primarily use relays | -| **Unknown** | NAT behavior could not be determined | Check UDP connectivity | - -### Connectivity Summary - -The report includes a color-coded connectivity summary: - -- **Green** — UDP works and NAT is favorable. Direct connections should work. -- **Orange** — Endpoint-Dependent NAT. Direct connections may be difficult; traffic will often be relayed. -- **Red** — No UDP connectivity. Traffic will be relayed. - -## Integrating Net Diagnostics Into Your App - -To add net diagnostics support to your own iroh application, you need to: - -1. Connect to n0des with an `iroh_n0des::Client` -2. Grant the `NetDiagnosticsCap::GetAny` capability to n0des so it can request diagnostics from your endpoint -3. Run a `ClientHost` so n0des can dial back into your endpoint - -Here's a minimal integration: - -```rust -use anyhow::Result; -use iroh::{Endpoint, protocol::Router}; -use iroh_n0des::{ - ApiSecret, Client, ClientHost, CLIENT_HOST_ALPN, API_SECRET_ENV_VAR_NAME, - caps::NetDiagnosticsCap, -}; - -async fn setup_net_diagnostics(endpoint: &Endpoint) -> Result { - // Parse the API secret from the environment - let secret = ApiSecret::from_env_var(API_SECRET_ENV_VAR_NAME)?; - let remote_id = secret.addr().id; - - // Build the n0des client - let client = Client::builder(endpoint) - .api_secret(secret)? - .build() - .await?; - - // Grant the GetAny capability so n0des can request diagnostics - // from this endpoint on demand - let client2 = client.clone(); - tokio::spawn(async move { - client2 - .grant_capability(remote_id, vec![NetDiagnosticsCap::GetAny]) - .await - .unwrap(); - }); - - // Set up a ClientHost so n0des can dial back into this endpoint - let host = ClientHost::new(endpoint); - let router = Router::builder(endpoint.clone()) - .accept(CLIENT_HOST_ALPN, host) - .spawn(); - - Ok(router) -} -``` - -Add the following to your `Cargo.toml`: - -```toml -[dependencies] -iroh-n0des = { version = "...", features = ["net_diagnostics", "client_host"] } -``` - -### How It Works - -When you click **Run Diagnostics** in the dashboard, n0des dials back into your endpoint using the capability token your app granted. Your `ClientHost` receives the request, runs the diagnostics locally (probing UDP connectivity, NAT behavior, relay latency, and port mapping), and returns the report to n0des for display. - -The capability grant (`NetDiagnosticsCap::GetAny`) authorizes n0des to request diagnostics from your endpoint. Without this grant, the **Run Diagnostics** button will be disabled in the dashboard even if the endpoint is online. - -### Requirements - -- The `net_diagnostics` and `client_host` cargo features must be enabled on `iroh-n0des` -- The `N0DES_API_SECRET` environment variable must be set before your app starts -- The `ClientHost` must be registered on the `Router` with `CLIENT_HOST_ALPN` so n0des can reach it diff --git a/iroh-services/net-diagnostics/quickstart.mdx b/iroh-services/net-diagnostics/quickstart.mdx new file mode 100644 index 0000000..ffe2a58 --- /dev/null +++ b/iroh-services/net-diagnostics/quickstart.mdx @@ -0,0 +1,56 @@ +--- +title: "Quickstart" +description: "Diagnose user connectivity issues with remote diagnostic reporting" +--- + +Net Diagnostics lets you run network connectivity reports on your endpoints. + +Reports cover NAT type, UDP connectivity, relay latency, port +mapping protocol availability, and direct addresses — everything you need to +debug connection issues. + +You can initiate reports from iroh-services, which will reach out to configured +remote nodes that have authorized diagnostics, gather +details about the endpoint's connectivity context, and forward the report to +your project on iroh services to assess how to help your user get the best +connection they can. + + +#### 1. Get your API secret + +Go to your project's **Settings** page and copy the API secret. In your terminal, export it as an environment variable: + +```bash +export N0DES_API_SECRET= +``` + +### 2. Run the diagnostics client + +Clone the repository and run the `net_diagnostics` example: + +```bash +git clone https://github.com/n0-computer/iroh-n0des.git +cd iroh-n0des +cargo run --example net_diagnostics --features net_diagnostics,client_host +``` + +Leave this terminal open. The example connects to n0des, grants the diagnostics capability to your project, and waits for incoming diagnostics requests. + +### 3. Run a diagnostic from the dashboard + +Go to your project's **Endpoints** page. You should see the example client listed as an online endpoint. Click **Run Diagnostics** to generate a report. + +The report appears on the **Net Diagnostics** page and includes: + +- **NAT Type** — No NAT, Endpoint-Independent, Endpoint-Dependent, or Unknown +- **UDP Connectivity** — IPv4 and IPv6 status with public addresses +- **NAT Mapping** — whether mapping varies by destination (symmetric NAT detection) +- **Direct Addresses** — local addresses the endpoint is listening on +- **Port Mapping** — UPnP, PCP, and NAT-PMP availability +- **Relay Latencies** — per-relay IPv4, IPv6, and HTTPS round-trip times +- **Captive Portal** — detection of captive portal interference + +## Next Steps + +- [Integrate diagnostics into your own app with the usage guide](./usage) to get on-demand reports from your users' endpoints. +- [Learn more about report details](./reports) to understand what each metric means and how it impacts connectivity. diff --git a/iroh-services/net-diagnostics/reports.mdx b/iroh-services/net-diagnostics/reports.mdx new file mode 100644 index 0000000..0c6d4ad --- /dev/null +++ b/iroh-services/net-diagnostics/reports.mdx @@ -0,0 +1,25 @@ + +### NAT Types + +| NAT Type | What it means | Connection quality | +|---|---|---| +| **No NAT** | Local address matches public address | Direct connections work with correct firewall config | +| **Endpoint-Independent** | One outbound UDP packet opens a port for any sender | Holepunching works reliably | +| **Endpoint-Dependent** | Only the specific destination can reply (symmetric NAT) | Connections will primarily use relays | +| **Unknown** | NAT behavior could not be determined | Check UDP connectivity | + +### Connectivity Summary + +The report includes a color-coded connectivity summary: + +- **Green** — UDP works and NAT is favorable. Direct connections should work. +- **Orange** — Endpoint-Dependent NAT. Direct connections may be difficult; traffic will often be relayed. +- **Red** — No UDP connectivity. Traffic will be relayed. + +## How It Works + +When you click **Run Diagnostics** in the dashboard, the platform dials back +into your endpoint using the capability token your app granted. Your +`ClientHost` receives the request, runs the diagnostics locally (probing UDP +connectivity, NAT behavior, relay latency, and port mapping), and returns the +report to the platform for display. diff --git a/iroh-services/net-diagnostics/usage.mdx b/iroh-services/net-diagnostics/usage.mdx new file mode 100644 index 0000000..249270d --- /dev/null +++ b/iroh-services/net-diagnostics/usage.mdx @@ -0,0 +1,93 @@ +--- +title: "Usage" +description: "Diagnose user connectivity issues with remote diagnostic reporting" +--- + +When you click **Run Diagnostics** in the dashboard, the platform dials back into your +endpoint using the capability token your app granted. Your `ClientHost` receives +the request, runs the diagnostics locally (probing UDP connectivity, NAT +behavior, relay latency, and port mapping), and returns the report to n0des for +display. + +## Integrating Net Diagnostics Into Your App + +To add net diagnostics support to your own iroh application, you need to: + +1. Connect to the n0des platform with an `iroh_n0des::Client` +2. Grant the `NetDiagnosticsCap::GetAny` capability to n0des so it can request diagnostics from your endpoint +3. Run a `ClientHost` so n0des can dial back into your endpoint + +[See the `net_diagnostics` example in the `iroh-n0des` repository for a complete working example of this integration.](https://github.com/n0-computer/iroh-n0des/tree/main/examples/net_diagnostics.rs) + + +### 1. Update Cargo.toml +Add the following to your `Cargo.toml`: + +```toml +[dependencies] +iroh-n0des = { version = "...", features = ["net_diagnostics", "client_host"] } +``` + +### 2. Get Your API Secret + +Go to your project's **Settings** page and copy the API secret. In your +terminal, export it as an environment variable or config file, or hardcode it in your app (not +recommended for production): + +```bash +export N0DES_API_SECRET= +``` + +### 3. Connect to n0des and Grant Capability + +Here's a minimal integration: + +```rust +use anyhow::Result; +use iroh::{Endpoint, protocol::Router}; +use iroh_n0des::{ + ApiSecret, Client, ClientHost, CLIENT_HOST_ALPN, API_SECRET_ENV_VAR_NAME, + caps::NetDiagnosticsCap, +}; + +async fn setup_net_diagnostics(endpoint: &Endpoint) -> Result { + // Get your secret somehow, either from an environment variable or config file + let secret = ApiSecret::from_env_var(API_SECRET_ENV_VAR_NAME)?; + + // The remote_id is the id of the endpoint we'll be sending the network + // report to, derived from the secret's address + let remote_id = secret.addr().id; + + // Build the client + let client = Client::builder(endpoint) + .api_secret(secret)? + .build() + .await?; + + // Grant the GetAny capability so the platform can request diagnostics + // from this endpoint on demand + let client2 = client.clone(); + tokio::spawn(async move { + client2 + .grant_capability(remote_id, vec![NetDiagnosticsCap::GetAny]) + .await + .unwrap(); + }); + + // Set up a ClientHost so the platform can dial back into this endpoint + let host = ClientHost::new(endpoint); + let router = Router::builder(endpoint.clone()) + .accept(CLIENT_HOST_ALPN, host) + .spawn(); + + Ok(router) +} +``` + + +## Troubleshooting + +The capability grant (`NetDiagnosticsCap::GetAny`) authorizes the platform to +request diagnostics from your endpoint. Without this grant, the **Run +Diagnostics** button will be disabled in the dashboard even if the endpoint is +online. diff --git a/iroh-services/quickstart.mdx b/iroh-services/quickstart.mdx index dcfcc77..5dbdb33 100644 --- a/iroh-services/quickstart.mdx +++ b/iroh-services/quickstart.mdx @@ -3,7 +3,7 @@ title: "Quickstart" description: "Get started with Iroh Services in minutes" --- -This guide will walk you through setting up your first Iroh Services-enabled application. +This guide will walk you through hooking up your first endpoint to Iroh Services. ## Prerequisites @@ -36,14 +36,15 @@ this to authenticate your endpoints. Add the `iroh-n0des` crate to your `Cargo.toml`: -```toml -[dependencies] -iroh = "0.35" -iroh-n0des = "0.1" ``` +cargo add iroh-n0des +``` + ## Step 4: Connect Your Endpoint +Then, in your code, create a client and connect your endpoint to Iroh Services. + ```rust use iroh::Endpoint; use iroh_n0des::Client; @@ -65,8 +66,20 @@ async fn main() -> anyhow::Result<()> { } ``` +## Step 5: View Your Endpoint on the Dashboard + +Go to your project's **Endpoints** page. You should see your endpoint listed as +online. Click on it to view details. + +## Step 6: View Metrics + +Navigate to the **Metrics** tab to see real-time and historical metrics about your endpoint's connectivity, direct data rate, and more. + +![Metrics Dashboard](/images/metrics-dashboard.png) + ## Next Steps - [Access Control](/iroh-services/access): Learn how to manage API keys and permissions - [Metrics](/iroh-services/metrics): Understand the metrics collected by Iroh Services - [Relays](/iroh-services/relays): Set up dedicated relay servers for your network +- [Net Diagnostics](/iroh-services/net-diagnostics): Run remote diagnostics on your endpoints to understand connectivity issues