diff --git a/assets/agw-docs/pages/operations/agctl-install.md b/assets/agw-docs/pages/operations/agctl-install.md new file mode 100644 index 000000000..08442aa26 --- /dev/null +++ b/assets/agw-docs/pages/operations/agctl-install.md @@ -0,0 +1,89 @@ +`agctl` is the CLI tool for controlling and debugging agentgateway. Use it to inspect configuration, trace live requests, and interact with running gateway instances. + +## Install agctl + +Download the `agctl` binary for your platform from the [agentgateway releases page](https://github.com/agentgateway/agentgateway/releases). + +{{< tabs tabTotal="3" items="Linux,macOS,Windows" >}} +{{% tab tabName="Linux" %}} + +```sh +curl -sL https://github.com/agentgateway/agentgateway/releases/latest/download/agctl-linux-amd64 -o agctl +chmod +x agctl +sudo mv agctl /usr/local/bin/agctl +``` + +{{% /tab %}} +{{% tab tabName="macOS" %}} + +```sh +# Intel +curl -sL https://github.com/agentgateway/agentgateway/releases/latest/download/agctl-darwin-amd64 -o agctl + +# Apple Silicon +curl -sL https://github.com/agentgateway/agentgateway/releases/latest/download/agctl-darwin-arm64 -o agctl + +chmod +x agctl +sudo mv agctl /usr/local/bin/agctl +``` + +{{% /tab %}} +{{% tab tabName="Windows" %}} + +Download `agctl-windows-amd64.exe` from the [releases page](https://github.com/agentgateway/agentgateway/releases) and add it to your `PATH`. + +{{% /tab %}} +{{< /tabs >}} + +## Verify the installation + +```sh +agctl --help +``` + +Example output: + +``` +agctl controls and inspects Agentgateway resources + +Usage: + agctl [command] + +Available Commands: + config Retrieve Agentgateway configuration for a resource + trace Trace the next request handled by an Agentgateway pod or local instance + help Help about any command + +Flags: + -h, --help help for agctl +``` + +## Upgrade agctl + +To upgrade, download the new binary from the [releases page](https://github.com/agentgateway/agentgateway/releases) and replace the existing binary following the same steps as installation. + +## Commands + +| Command | Description | +|---------|-------------| +| [`agctl config`](#agctl-config) | Retrieve agentgateway configuration for a resource. | +| [`agctl trace`]({{< link-hextra path="/operations/agctl-trace/" >}}) | Trace the next request handled by an agentgateway pod or local instance. | + +### agctl config + +Retrieve the current configuration from a running agentgateway instance. + +```sh +# All configuration +agctl config all + +# Backend configuration only +agctl config backends +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `-n, --namespace` | | Namespace for resource resolution. | +| `-f, --file` | | Path to an agentgateway config dump JSON file. | +| `--proxy-admin-port` | `15000` | Admin port. | +| `-o, --output` | `short` | Output format: `short`, `json`, or `yaml`. | diff --git a/assets/agw-docs/pages/operations/agctl-trace.md b/assets/agw-docs/pages/operations/agctl-trace.md new file mode 100644 index 000000000..55111764d --- /dev/null +++ b/assets/agw-docs/pages/operations/agctl-trace.md @@ -0,0 +1,101 @@ +Use `agctl trace` to inspect the next request handled by agentgateway in real time. The command connects to the admin API and streams trace events — showing the route matched, policies applied, filters evaluated, and the final response — either in an interactive TUI or as raw JSONL. + +## Before you begin + +- Install `agctl`. See [Install agctl]({{< link-hextra path="/operations/agctl/" >}}). +- Have a running agentgateway instance. + +## Trace a request + +Run `agctl trace` to watch for the next incoming request. The command blocks until a request arrives, then renders the trace in an interactive TUI. + +{{< tabs tabTotal="2" items="Kubernetes,Standalone" >}} +{{% tab tabName="Kubernetes" %}} + +Watch for the next request on the auto-detected gateway pod: + +```sh +agctl trace +``` + +Target a specific gateway resource: + +```sh +agctl trace gateway/my-gateway +``` + +Watch in a specific namespace: + +```sh +agctl trace gateway/my-gateway -n my-namespace +``` + +{{% /tab %}} +{{% tab tabName="Standalone" %}} + +Trace against a local agentgateway instance: + +```sh +agctl trace --local +``` + +If agentgateway is listening on a non-default admin port: + +```sh +agctl trace --local --proxy-admin-port 15001 +``` + +{{% /tab %}} +{{< /tabs >}} + +## Trigger a request as part of the trace + +Pass a URL after `--` to have `agctl` both enable tracing and send the request. Use `--port` to specify the gateway listener port. + +{{< tabs tabTotal="2" items="Kubernetes,Standalone" >}} +{{% tab tabName="Kubernetes" %}} + +```sh +agctl trace gateway/my-gateway --port 80 -- http://host/some/path +``` + +With additional curl arguments (for example, a bearer token): + +```sh +agctl trace gateway/my-gateway --port 80 -- http://host/some/path -H "Authorization: Bearer sk-123" +``` + +{{% /tab %}} +{{% tab tabName="Standalone" %}} + +```sh +agctl trace --local --port 8080 -- http://host/some/path +``` + +With additional curl arguments: + +```sh +agctl trace --local --port 8080 -- http://host/some/path -H "Authorization: Bearer sk-123" +``` + +{{% /tab %}} +{{< /tabs >}} + +## Output raw JSONL instead of the TUI + +Use `--raw` to print trace events as newline-delimited JSON (JSONL) instead of opening the interactive TUI. This is useful for scripting or piping to tools like `jq`. + +```sh +agctl trace --raw +agctl trace gateway/my-gateway --raw --port 80 -- http://host/some/path | jq . +``` + +## Reference + +| Flag | Default | Description | +|------|---------|-------------| +| `-n, --namespace` | | Namespace to use when resolving resources. | +| `--proxy-admin-port` | `15000` | Agentgateway admin port. | +| `--raw` | `false` | Print trace events as JSONL instead of opening the TUI. | +| `--port` | | Gateway listener port to use when triggering a request. Required when a request URL is provided. | +| `--local` | `false` | Trace against a local agentgateway instance on `127.0.0.1`. Cannot be combined with a resource argument. | diff --git a/assets/agw-docs/pages/operations/debug-standalone.md b/assets/agw-docs/pages/operations/debug-standalone.md index d85b5c2c9..8ee7f646f 100644 --- a/assets/agw-docs/pages/operations/debug-standalone.md +++ b/assets/agw-docs/pages/operations/debug-standalone.md @@ -1,5 +1,9 @@ Use built-in tools to troubleshoot issues in your standalone agentgateway setup. +## Trace live requests {#trace} + +Use `agctl trace` to inspect the next request handled by agentgateway in real time, including the route matched, policies applied, and the final response. See [Trace requests]({{< link-hextra path="/operations/agctl-trace/" >}}) for full details. + ## Enable debug logs {#debug-logs} Enable debug logs in agentgateway. You can choose between two methods: using the logging endpoint or updating the config file. diff --git a/assets/agw-docs/pages/operations/debug.md b/assets/agw-docs/pages/operations/debug.md index 00c380920..6c06eca92 100644 --- a/assets/agw-docs/pages/operations/debug.md +++ b/assets/agw-docs/pages/operations/debug.md @@ -1,5 +1,9 @@ Use built-in tools to troubleshoot issues in your {{< reuse "/agw-docs/snippets/kgateway.md" >}} setup. +## Trace live requests {#trace} + +Use `agctl trace` to inspect the next request handled by agentgateway in real time, including the route matched, policies applied, and the final response. See [Trace requests]({{< link-hextra path="/operations/agctl-trace/" >}}) for full details. + {{< reuse "/agw-docs/snippets/agentgateway-capital.md" >}} consists of the control plane and an {{< reuse "/agw-docs/snippets/data-plane.md" >}} data plane. If you experience issues in your environment, such as policies that are not applied or traffic that is not routed correctly, in a lot of cases, these errors can be observed at the proxy. ## Debug the control plane {#control-plane} diff --git a/content/docs/kubernetes/latest/operations/agctl-trace.md b/content/docs/kubernetes/latest/operations/agctl-trace.md new file mode 100644 index 000000000..af2716b31 --- /dev/null +++ b/content/docs/kubernetes/latest/operations/agctl-trace.md @@ -0,0 +1,7 @@ +--- +title: Trace requests +weight: 30 +description: Use agctl trace to inspect live requests flowing through your agentgateway deployment. +--- + +{{< reuse "agw-docs/pages/operations/agctl-trace.md" >}} diff --git a/content/docs/kubernetes/latest/operations/agctl.md b/content/docs/kubernetes/latest/operations/agctl.md new file mode 100644 index 000000000..8314a4b4a --- /dev/null +++ b/content/docs/kubernetes/latest/operations/agctl.md @@ -0,0 +1,7 @@ +--- +title: agctl CLI +weight: 25 +description: Install and use the agctl CLI to debug and inspect your agentgateway deployment. +--- + +{{< reuse "agw-docs/pages/operations/agctl-install.md" >}} diff --git a/content/docs/kubernetes/main/operations/agctl-trace.md b/content/docs/kubernetes/main/operations/agctl-trace.md new file mode 100644 index 000000000..af2716b31 --- /dev/null +++ b/content/docs/kubernetes/main/operations/agctl-trace.md @@ -0,0 +1,7 @@ +--- +title: Trace requests +weight: 30 +description: Use agctl trace to inspect live requests flowing through your agentgateway deployment. +--- + +{{< reuse "agw-docs/pages/operations/agctl-trace.md" >}} diff --git a/content/docs/kubernetes/main/operations/agctl.md b/content/docs/kubernetes/main/operations/agctl.md new file mode 100644 index 000000000..8314a4b4a --- /dev/null +++ b/content/docs/kubernetes/main/operations/agctl.md @@ -0,0 +1,7 @@ +--- +title: agctl CLI +weight: 25 +description: Install and use the agctl CLI to debug and inspect your agentgateway deployment. +--- + +{{< reuse "agw-docs/pages/operations/agctl-install.md" >}} diff --git a/content/docs/standalone/latest/operations/agctl-trace.md b/content/docs/standalone/latest/operations/agctl-trace.md new file mode 100644 index 000000000..b5b741e45 --- /dev/null +++ b/content/docs/standalone/latest/operations/agctl-trace.md @@ -0,0 +1,7 @@ +--- +title: Trace requests +weight: 25 +description: Use agctl trace to inspect live requests flowing through your standalone agentgateway. +--- + +{{< reuse "agw-docs/pages/operations/agctl-trace.md" >}} diff --git a/content/docs/standalone/latest/operations/agctl.md b/content/docs/standalone/latest/operations/agctl.md new file mode 100644 index 000000000..8e9bee17d --- /dev/null +++ b/content/docs/standalone/latest/operations/agctl.md @@ -0,0 +1,7 @@ +--- +title: agctl CLI +weight: 20 +description: Install and use the agctl CLI to debug and inspect your standalone agentgateway. +--- + +{{< reuse "agw-docs/pages/operations/agctl-install.md" >}} diff --git a/content/docs/standalone/main/operations/agctl-trace.md b/content/docs/standalone/main/operations/agctl-trace.md new file mode 100644 index 000000000..b5b741e45 --- /dev/null +++ b/content/docs/standalone/main/operations/agctl-trace.md @@ -0,0 +1,7 @@ +--- +title: Trace requests +weight: 25 +description: Use agctl trace to inspect live requests flowing through your standalone agentgateway. +--- + +{{< reuse "agw-docs/pages/operations/agctl-trace.md" >}} diff --git a/content/docs/standalone/main/operations/agctl.md b/content/docs/standalone/main/operations/agctl.md new file mode 100644 index 000000000..8e9bee17d --- /dev/null +++ b/content/docs/standalone/main/operations/agctl.md @@ -0,0 +1,7 @@ +--- +title: agctl CLI +weight: 20 +description: Install and use the agctl CLI to debug and inspect your standalone agentgateway. +--- + +{{< reuse "agw-docs/pages/operations/agctl-install.md" >}}