synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-12 00:14:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): document agent api debug endpoints (#14454)

Browse Source 
* chore(docs): add agent api debug docs

* chore(docs): add sections to agent api readme

* chore(docs): link debug manifest to agentsdk.Manifest schema

* chore(docs): add high level overview of agent api debug docs

* chore(docs): link to agent api docs from reference

* chore(docs): fix invalid paths

* chore(docs): use env variable for coder agent debug address
This commit is contained in:
Danielle Maywood
2024-08-28 09:47:14 +01:00
committed by GitHub
parent 8c15192433
commit 839918c5e7
6 changed files with 223 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
agent/agent.go
View File

@ -1787,7 +1787,7 @@ func (a *agent) HandleHTTPDebugLogs(w http.ResponseWriter, r *http.Request) {
}
defer f.Close()
// Limit to 10MB.
// Limit to 10MiB.
w.WriteHeader(http.StatusOK)
_, err = io.Copy(w, io.LimitReader(f, 10*1024*1024))
if err != nil && !errors.Is(err, io.EOF) {

16
docs/manifest.json
View File

@ -1105,6 +1105,22 @@
"path": "reference/cli/whoami.md"
}
]
},
{
"title": "Agent API",
"description": "Learn how to use Coder Agent API",
"path": "./reference/agent-api/README.md",
"icon_path": "./images/icons/api.svg",
"children": [
{
"title": "Debug",
"path": "./reference/agent-api/debug.md"
},
{
"title": "Schemas",
"path": "./reference/agent-api/schemas.md"
}
]
}
]
},

1
docs/reference/README.md
View File

@ -4,3 +4,4 @@ Autogenerated documentation around Coder.
- [REST API](./api)
- [Command Line](./cli)
- [Agent API](./agent-api)

5
docs/reference/agent-api/README.md Normal file
View File

@ -0,0 +1,5 @@
## Sections
<children>
This page is rendered on https://coder.com/docs/reference/agent-api. Refer to the other documents in the `agent-api/` directory.
</children>

76
docs/reference/agent-api/debug.md Normal file
View File

@ -0,0 +1,76 @@
# Debug
## Get debug logs
### Code samples
```shell
curl $CODER_AGENT_DEBUG_ADDRESS/debug/logs
```
`GET /debug/logs`
Get the first 10MiB of data from `$CODER_AGENT_LOG_DIR/coder-agent.log`.
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------ |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | |
## Get debug info for magicsock
### Code samples
```shell
curl $CODER_AGENT_DEBUG_ADDRESS/debug/magicsock
```
`GET /debug/magicsock`
See
[Tailscale's documentation](https://pkg.go.dev/tailscale.com/wgengine/magicsock#Conn.ServeHTTPDebug).
## Toggle debug logging for magicsock
### Code samples
```shell
curl $CODER_AGENT_DEBUG_ADDRESS/debug/magicsock/debug-logging/true
```
`GET /debug/magicsock/debug-logging/{state}`
Set whether debug logging is enabled. See
[Tailscale's documentation](https://pkg.go.dev/tailscale.com/wgengine/magicsock#Conn.SetDebugLoggingEnabled)
for more information.
### Parameters
| Name | In | Type | Required | Description |
| ------- | ---- | ------- | -------- | ------------------- |
| `state` | path | boolean | true | Debug logging state |
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------ |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | |
## Get debug manifest
### Code samples
```shell
curl $CODER_AGENT_DEBUG_ADDRESS/debug/manifest
```
`GET /debug/manifest`
Get the manifest the agent fetched from `coderd` upon startup.
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.Manifest](./schemas.md#agentsdkmanifest) |

124
docs/reference/agent-api/schemas.md Normal file
View File

@ -0,0 +1,124 @@
# Schemas
## agentsdk.Manifest
```json
{
"agent_id": "151321db-0713-473c-ab42-2cc6ddeab1a4",
"agent_name": "string",
"owner_name": "string",
"workspace_id": "8ef13a0d-a5c9-4fb4-abf2-f8f65c3830fb",
"workspace_name": "string",
"git_auth_configs": 1,
"vscode_port_proxy_uri": "string",
"apps": [
{
"id": "c488c933-688a-444e-a55d-f1e88ecc78f5",
"url": "string",
"external": false,
"slug": "string",
"display_name": "string",
"icon": "string",
"subdomain": false,
"sharing_level": "owner",
"healthcheck": {
"url": "string",
"interval": 5,
"threshold": 6
},
"health": "initializing"
}
],
"derpmap": {
"HomeParams": {},
"Regions": {
"1000": {
"EmbeddedRelay": false,
"RegionID": 1000,
"RegionCode": "string",
"RegionName": "string",
"Nodes": [
{
"Name": "string",
"RegionID": 1000,
"HostName": "string",
"STUNPort": 19302,
"STUNOnly": true
}
]
}
}
},
"derp_force_websockets": false,
"environment_variables": {
"OIDC_TOKEN": "string"
},
"directory": "string",
"motd_file": "string",
"disable_direct_connections": false,
"metadata": [
{
"display_name": "string",
"key": "string",
"script": "string",
"interval": 10,
"timeout": 1
}
],
"scripts": [
{
"log_source_id": "3e79c8da-08ae-48f4-b73e-11e194cdea06",
"log_path": "string",
"script": "string",
"cron": "string",
"run_on_start": true,
"run_on_stop": false,
"start_blocks_login": true,
"timeout": 0
}
]
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------- | -------- | ------------ | ----------- |
| `agent_id` | string | true | | |
| `agent_name` | string | true | | |
| `owner_name` | string | true | | |
| `workspace_id` | string | true | | |
| `workspace_name` | string | true | | |
| `git_auth_configs` | int | true | | |
| `vscode_port_proxy_uri` | string | true | | |
| `apps` | array of [codersdk.WorkspaceApp](../api/schemas.md#codersdkworkspaceapp) | true | | |
| `derpmap` | [tailcfg.DERPMap](../api/schemas.md#tailcfgderpmap) | true | | |
| `derp_force_websockets` | boolean | true | | |
| `environment_variables` | object | true | | |
| `directory` | string | true | | |
| `motd_file` | string | true | | |
| `disable_direct_connections` | boolean | true | | |
| `metadata` | array of [codersdk.WorkspaceAgentMetadataDescription](#codersdkworkspaceagentmetadatadescription) | true | | |
| `scripts` | array of [codersdk.WorkspaceAgentScript](../api/schemas.md#codersdkworkspaceagentscript) | true | | |
## codersdk.WorkspaceAgentMetadataDescription
```json
{
"display_name": "string",
"key": "string",
"script": "string",
"interval": 10,
"timeout": 1
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| -------------- | ------- | -------- | ------------ | ----------- |
| `display_name` | string | true | | |
| `key` | string | true | | |
| `script` | string | true | | |
| `interval` | integer | true | | |
| `timeout` | integer | true | | |