Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 839918c

Browse files
DanielleMaywoodDanielleMaywood
authored
chore(docs): document agent api debug endpoints (coder#14454)
* 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
1 parent 8c15192 commit 839918c

File tree

6 files changed

+223
-1
lines changed

6 files changed

+223
-1
lines changed

‎agent/agent.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -1787,7 +1787,7 @@ func (a *agent) HandleHTTPDebugLogs(w http.ResponseWriter, r *http.Request) {
17871787
}
17881788
defer f.Close()
17891789

1790-
// Limit to 10MB.
1790+
// Limit to 10MiB.
17911791
w.WriteHeader(http.StatusOK)
17921792
_, err = io.Copy(w, io.LimitReader(f, 10*1024*1024))
17931793
if err != nil && !errors.Is(err, io.EOF) {

‎docs/manifest.json

+16
Original file line numberDiff line numberDiff line change
@@ -1105,6 +1105,22 @@
11051105
"path": "reference/cli/whoami.md"
11061106
}
11071107
]
1108+
},
1109+
{
1110+
"title": "Agent API",
1111+
"description": "Learn how to use Coder Agent API",
1112+
"path": "./reference/agent-api/README.md",
1113+
"icon_path": "./images/icons/api.svg",
1114+
"children": [
1115+
{
1116+
"title": "Debug",
1117+
"path": "./reference/agent-api/debug.md"
1118+
},
1119+
{
1120+
"title": "Schemas",
1121+
"path": "./reference/agent-api/schemas.md"
1122+
}
1123+
]
11081124
}
11091125
]
11101126
},

‎docs/reference/README.md

+1
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ Autogenerated documentation around Coder.
44

55
- [REST API](./api)
66
- [Command Line](./cli)
7+
- [Agent API](./agent-api)

‎docs/reference/agent-api/README.md

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

‎docs/reference/agent-api/debug.md

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Debug
2+
3+
## Get debug logs
4+
5+
### Code samples
6+
7+
```shell
8+
curl $CODER_AGENT_DEBUG_ADDRESS/debug/logs
9+
```
10+
11+
`GET /debug/logs`
12+
13+
Get the first 10MiB of data from `$CODER_AGENT_LOG_DIR/coder-agent.log`.
14+
15+
### Responses
16+
17+
| Status | Meaning | Description | Schema |
18+
| ------ | ------------------------------------------------------- | ----------- | ------ |
19+
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | |
20+
21+
## Get debug info for magicsock
22+
23+
### Code samples
24+
25+
```shell
26+
curl $CODER_AGENT_DEBUG_ADDRESS/debug/magicsock
27+
```
28+
29+
`GET /debug/magicsock`
30+
31+
See
32+
[Tailscale's documentation](https://pkg.go.dev/tailscale.com/wgengine/magicsock#Conn.ServeHTTPDebug).
33+
34+
## Toggle debug logging for magicsock
35+
36+
### Code samples
37+
38+
```shell
39+
curl $CODER_AGENT_DEBUG_ADDRESS/debug/magicsock/debug-logging/true
40+
```
41+
42+
`GET /debug/magicsock/debug-logging/{state}`
43+
44+
Set whether debug logging is enabled. See
45+
[Tailscale's documentation](https://pkg.go.dev/tailscale.com/wgengine/magicsock#Conn.SetDebugLoggingEnabled)
46+
for more information.
47+
48+
### Parameters
49+
50+
| Name | In | Type | Required | Description |
51+
| ------- | ---- | ------- | -------- | ------------------- |
52+
| `state` | path | boolean | true | Debug logging state |
53+
54+
### Responses
55+
56+
| Status | Meaning | Description | Schema |
57+
| ------ | ------------------------------------------------------- | ----------- | ------ |
58+
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | |
59+
60+
## Get debug manifest
61+
62+
### Code samples
63+
64+
```shell
65+
curl $CODER_AGENT_DEBUG_ADDRESS/debug/manifest
66+
```
67+
68+
`GET /debug/manifest`
69+
70+
Get the manifest the agent fetched from `coderd` upon startup.
71+
72+
### Responses
73+
74+
| Status | Meaning | Description | Schema |
75+
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------- |
76+
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.Manifest](./schemas.md#agentsdkmanifest) |

‎docs/reference/agent-api/schemas.md

+124
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Schemas
2+
3+
## agentsdk.Manifest
4+
5+
```json
6+
{
7+
"agent_id": "151321db-0713-473c-ab42-2cc6ddeab1a4",
8+
"agent_name": "string",
9+
"owner_name": "string",
10+
"workspace_id": "8ef13a0d-a5c9-4fb4-abf2-f8f65c3830fb",
11+
"workspace_name": "string",
12+
"git_auth_configs": 1,
13+
"vscode_port_proxy_uri": "string",
14+
"apps": [
15+
{
16+
"id": "c488c933-688a-444e-a55d-f1e88ecc78f5",
17+
"url": "string",
18+
"external": false,
19+
"slug": "string",
20+
"display_name": "string",
21+
"icon": "string",
22+
"subdomain": false,
23+
"sharing_level": "owner",
24+
"healthcheck": {
25+
"url": "string",
26+
"interval": 5,
27+
"threshold": 6
28+
},
29+
"health": "initializing"
30+
}
31+
],
32+
"derpmap": {
33+
"HomeParams": {},
34+
"Regions": {
35+
"1000": {
36+
"EmbeddedRelay": false,
37+
"RegionID": 1000,
38+
"RegionCode": "string",
39+
"RegionName": "string",
40+
"Nodes": [
41+
{
42+
"Name": "string",
43+
"RegionID": 1000,
44+
"HostName": "string",
45+
"STUNPort": 19302,
46+
"STUNOnly": true
47+
}
48+
]
49+
}
50+
}
51+
},
52+
"derp_force_websockets": false,
53+
"environment_variables": {
54+
"OIDC_TOKEN": "string"
55+
},
56+
"directory": "string",
57+
"motd_file": "string",
58+
"disable_direct_connections": false,
59+
"metadata": [
60+
{
61+
"display_name": "string",
62+
"key": "string",
63+
"script": "string",
64+
"interval": 10,
65+
"timeout": 1
66+
}
67+
],
68+
"scripts": [
69+
{
70+
"log_source_id": "3e79c8da-08ae-48f4-b73e-11e194cdea06",
71+
"log_path": "string",
72+
"script": "string",
73+
"cron": "string",
74+
"run_on_start": true,
75+
"run_on_stop": false,
76+
"start_blocks_login": true,
77+
"timeout": 0
78+
}
79+
]
80+
}
81+
```
82+
83+
### Properties
84+
85+
| Name | Type | Required | Restrictions | Description |
86+
| ---------------------------- | ------------------------------------------------------------------------------------------------- | -------- | ------------ | ----------- |
87+
| `agent_id` | string | true | | |
88+
| `agent_name` | string | true | | |
89+
| `owner_name` | string | true | | |
90+
| `workspace_id` | string | true | | |
91+
| `workspace_name` | string | true | | |
92+
| `git_auth_configs` | int | true | | |
93+
| `vscode_port_proxy_uri` | string | true | | |
94+
| `apps` | array of [codersdk.WorkspaceApp](../api/schemas.md#codersdkworkspaceapp) | true | | |
95+
| `derpmap` | [tailcfg.DERPMap](../api/schemas.md#tailcfgderpmap) | true | | |
96+
| `derp_force_websockets` | boolean | true | | |
97+
| `environment_variables` | object | true | | |
98+
| `directory` | string | true | | |
99+
| `motd_file` | string | true | | |
100+
| `disable_direct_connections` | boolean | true | | |
101+
| `metadata` | array of [codersdk.WorkspaceAgentMetadataDescription](#codersdkworkspaceagentmetadatadescription) | true | | |
102+
| `scripts` | array of [codersdk.WorkspaceAgentScript](../api/schemas.md#codersdkworkspaceagentscript) | true | | |
103+
104+
## codersdk.WorkspaceAgentMetadataDescription
105+
106+
```json
107+
{
108+
"display_name": "string",
109+
"key": "string",
110+
"script": "string",
111+
"interval": 10,
112+
"timeout": 1
113+
}
114+
```
115+
116+
### Properties
117+
118+
| Name | Type | Required | Restrictions | Description |
119+
| -------------- | ------- | -------- | ------------ | ----------- |
120+
| `display_name` | string | true | | |
121+
| `key` | string | true | | |
122+
| `script` | string | true | | |
123+
| `interval` | integer | true | | |
124+
| `timeout` | integer | true | | |

0 commit comments

Comments
 (0)