diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index a284e46d0a0bb..9b73496b9c749 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -1158,6 +1158,15 @@ const docTemplate = `{ ], "summary": "Get deployment DAUs", "operationId": "get-deployment-daus", + "parameters": [ + { + "type": "integer", + "description": "Time-zone offset (e.g. -2)", + "name": "tz_offset", + "in": "query", + "required": true + } + ], "responses": { "200": { "description": "OK", @@ -1185,18 +1194,41 @@ const docTemplate = `{ "operationId": "get-insights-about-templates", "parameters": [ { - "type": "integer", + "type": "string", + "format": "date-time", "description": "Start time", - "name": "before", + "name": "start_time", "in": "query", "required": true }, { - "type": "integer", + "type": "string", + "format": "date-time", "description": "End time", - "name": "after", + "name": "end_time", "in": "query", "required": true + }, + { + "enum": [ + "week", + "day" + ], + "type": "string", + "description": "Interval", + "name": "interval", + "in": "query", + "required": true + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "csv", + "description": "Template IDs", + "name": "template_ids", + "in": "query" } ], "responses": { @@ -1226,18 +1258,30 @@ const docTemplate = `{ "operationId": "get-insights-about-user-activity", "parameters": [ { - "type": "integer", + "type": "string", + "format": "date-time", "description": "Start time", - "name": "before", + "name": "start_time", "in": "query", "required": true }, { - "type": "integer", + "type": "string", + "format": "date-time", "description": "End time", - "name": "after", + "name": "end_time", "in": "query", "required": true + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "csv", + "description": "Template IDs", + "name": "template_ids", + "in": "query" } ], "responses": { @@ -1267,18 +1311,30 @@ const docTemplate = `{ "operationId": "get-insights-about-user-latency", "parameters": [ { - "type": "integer", + "type": "string", + "format": "date-time", "description": "Start time", - "name": "before", + "name": "start_time", "in": "query", "required": true }, { - "type": "integer", + "type": "string", + "format": "date-time", "description": "End time", - "name": "after", + "name": "end_time", "in": "query", "required": true + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "csv", + "description": "Template IDs", + "name": "template_ids", + "in": "query" } ], "responses": { diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 28212bdaa8342..de2ae4ffc34ac 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -998,6 +998,15 @@ "tags": ["Insights"], "summary": "Get deployment DAUs", "operationId": "get-deployment-daus", + "parameters": [ + { + "type": "integer", + "description": "Time-zone offset (e.g. -2)", + "name": "tz_offset", + "in": "query", + "required": true + } + ], "responses": { "200": { "description": "OK", @@ -1021,18 +1030,38 @@ "operationId": "get-insights-about-templates", "parameters": [ { - "type": "integer", + "type": "string", + "format": "date-time", "description": "Start time", - "name": "before", + "name": "start_time", "in": "query", "required": true }, { - "type": "integer", + "type": "string", + "format": "date-time", "description": "End time", - "name": "after", + "name": "end_time", "in": "query", "required": true + }, + { + "enum": ["week", "day"], + "type": "string", + "description": "Interval", + "name": "interval", + "in": "query", + "required": true + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "csv", + "description": "Template IDs", + "name": "template_ids", + "in": "query" } ], "responses": { @@ -1058,18 +1087,30 @@ "operationId": "get-insights-about-user-activity", "parameters": [ { - "type": "integer", + "type": "string", + "format": "date-time", "description": "Start time", - "name": "before", + "name": "start_time", "in": "query", "required": true }, { - "type": "integer", + "type": "string", + "format": "date-time", "description": "End time", - "name": "after", + "name": "end_time", "in": "query", "required": true + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "csv", + "description": "Template IDs", + "name": "template_ids", + "in": "query" } ], "responses": { @@ -1095,18 +1136,30 @@ "operationId": "get-insights-about-user-latency", "parameters": [ { - "type": "integer", + "type": "string", + "format": "date-time", "description": "Start time", - "name": "before", + "name": "start_time", "in": "query", "required": true }, { - "type": "integer", + "type": "string", + "format": "date-time", "description": "End time", - "name": "after", + "name": "end_time", "in": "query", "required": true + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "csv", + "description": "Template IDs", + "name": "template_ids", + "in": "query" } ], "responses": { diff --git a/coderd/insights.go b/coderd/insights.go index a54e79a525644..7234a88d44fe9 100644 --- a/coderd/insights.go +++ b/coderd/insights.go @@ -30,6 +30,7 @@ const insightsTimeLayout = time.RFC3339 // @Security CoderSessionToken // @Produce json // @Tags Insights +// @Param tz_offset query int true "Time-zone offset (e.g. -2)" // @Success 200 {object} codersdk.DAUsResponse // @Router /insights/daus [get] func (api *API) deploymentDAUs(rw http.ResponseWriter, r *http.Request) { @@ -100,8 +101,9 @@ func (api *API) returnDAUsInternal(rw http.ResponseWriter, r *http.Request, temp // @Security CoderSessionToken // @Produce json // @Tags Insights -// @Param before query int true "Start time" -// @Param after query int true "End time" +// @Param start_time query string true "Start time" format(date-time) +// @Param end_time query string true "End time" format(date-time) +// @Param template_ids query []string false "Template IDs" collectionFormat(csv) // @Success 200 {object} codersdk.UserActivityInsightsResponse // @Router /insights/user-activity [get] func (api *API) insightsUserActivity(rw http.ResponseWriter, r *http.Request) { @@ -202,8 +204,9 @@ func (api *API) insightsUserActivity(rw http.ResponseWriter, r *http.Request) { // @Security CoderSessionToken // @Produce json // @Tags Insights -// @Param before query int true "Start time" -// @Param after query int true "End time" +// @Param start_time query string true "Start time" format(date-time) +// @Param end_time query string true "End time" format(date-time) +// @Param template_ids query []string false "Template IDs" collectionFormat(csv) // @Success 200 {object} codersdk.UserLatencyInsightsResponse // @Router /insights/user-latency [get] func (api *API) insightsUserLatency(rw http.ResponseWriter, r *http.Request) { @@ -294,8 +297,10 @@ func (api *API) insightsUserLatency(rw http.ResponseWriter, r *http.Request) { // @Security CoderSessionToken // @Produce json // @Tags Insights -// @Param before query int true "Start time" -// @Param after query int true "End time" +// @Param start_time query string true "Start time" format(date-time) +// @Param end_time query string true "End time" format(date-time) +// @Param interval query string true "Interval" enums(week,day) +// @Param template_ids query []string false "Template IDs" collectionFormat(csv) // @Success 200 {object} codersdk.TemplateInsightsResponse // @Router /insights/templates [get] func (api *API) insightsTemplates(rw http.ResponseWriter, r *http.Request) { diff --git a/docs/api/insights.md b/docs/api/insights.md index 7dae576b847b8..eb1a7679a6708 100644 --- a/docs/api/insights.md +++ b/docs/api/insights.md @@ -6,13 +6,19 @@ ```shell # Example request using curl -curl -X GET http://coder-server:8080/api/v2/insights/daus \ +curl -X GET http://coder-server:8080/api/v2/insights/daus?tz_offset=0 \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' ``` `GET /insights/daus` +### Parameters + +| Name | In | Type | Required | Description | +| ----------- | ----- | ------- | -------- | -------------------------- | +| `tz_offset` | query | integer | true | Time-zone offset (e.g. -2) | + ### Example responses > 200 Response @@ -43,7 +49,7 @@ To perform this operation, you must be authenticated. [Learn more](authenticatio ```shell # Example request using curl -curl -X GET http://coder-server:8080/api/v2/insights/templates?before=0&after=0 \ +curl -X GET http://coder-server:8080/api/v2/insights/templates?start_time=2019-08-24T14%3A15%3A22Z&end_time=2019-08-24T14%3A15%3A22Z&interval=week \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' ``` @@ -52,10 +58,19 @@ curl -X GET http://coder-server:8080/api/v2/insights/templates?before=0&after=0 ### Parameters -| Name | In | Type | Required | Description | -| -------- | ----- | ------- | -------- | ----------- | -| `before` | query | integer | true | Start time | -| `after` | query | integer | true | End time | +| Name | In | Type | Required | Description | +| -------------- | ----- | ----------------- | -------- | ------------ | +| `start_time` | query | string(date-time) | true | Start time | +| `end_time` | query | string(date-time) | true | End time | +| `interval` | query | string | true | Interval | +| `template_ids` | query | array[string] | false | Template IDs | + +#### Enumerated Values + +| Parameter | Value | +| ---------- | ------ | +| `interval` | `week` | +| `interval` | `day` | ### Example responses @@ -129,7 +144,7 @@ To perform this operation, you must be authenticated. [Learn more](authenticatio ```shell # Example request using curl -curl -X GET http://coder-server:8080/api/v2/insights/user-activity?before=0&after=0 \ +curl -X GET http://coder-server:8080/api/v2/insights/user-activity?start_time=2019-08-24T14%3A15%3A22Z&end_time=2019-08-24T14%3A15%3A22Z \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' ``` @@ -138,10 +153,11 @@ curl -X GET http://coder-server:8080/api/v2/insights/user-activity?before=0&afte ### Parameters -| Name | In | Type | Required | Description | -| -------- | ----- | ------- | -------- | ----------- | -| `before` | query | integer | true | Start time | -| `after` | query | integer | true | End time | +| Name | In | Type | Required | Description | +| -------------- | ----- | ----------------- | -------- | ------------ | +| `start_time` | query | string(date-time) | true | Start time | +| `end_time` | query | string(date-time) | true | End time | +| `template_ids` | query | array[string] | false | Template IDs | ### Example responses @@ -180,7 +196,7 @@ To perform this operation, you must be authenticated. [Learn more](authenticatio ```shell # Example request using curl -curl -X GET http://coder-server:8080/api/v2/insights/user-latency?before=0&after=0 \ +curl -X GET http://coder-server:8080/api/v2/insights/user-latency?start_time=2019-08-24T14%3A15%3A22Z&end_time=2019-08-24T14%3A15%3A22Z \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' ``` @@ -189,10 +205,11 @@ curl -X GET http://coder-server:8080/api/v2/insights/user-latency?before=0&after ### Parameters -| Name | In | Type | Required | Description | -| -------- | ----- | ------- | -------- | ----------- | -| `before` | query | integer | true | Start time | -| `after` | query | integer | true | End time | +| Name | In | Type | Required | Description | +| -------------- | ----- | ----------------- | -------- | ------------ | +| `start_time` | query | string(date-time) | true | Start time | +| `end_time` | query | string(date-time) | true | End time | +| `template_ids` | query | array[string] | false | Template IDs | ### Example responses