From 4affb639646eeb3ada0577591512a85ccb96e8b2 Mon Sep 17 00:00:00 2001 From: James Cotter Date: Wed, 28 May 2025 18:09:37 +0100 Subject: [PATCH 01/14] Add Analytics access token docs --- docs/analytics/cloud.mdx | 95 +++++++++++++++++++++++++++++++++++++++- docs/analytics/index.mdx | 2 +- public/llms.txt | 4 +- 3 files changed, 97 insertions(+), 4 deletions(-) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index 5f3ca4397..7ccfe4a6f 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -11,8 +11,101 @@ To enable Sourcegraph Analytics: - Create an account on [Sourcegraph Accounts](https://accounts.sourcegraph.com/), or find the email address associated with your existing account. - Contact your Sourcegraph Technical Advisor or point of contact (or email us at support@sourcegraph.com if you don't know your contact), provide them with the email address you used to register above and ask for access to Sourcegraph Analytics. - They will validate your account and link it to your Sourcegraph Enterprise instance's usage metrics. -- Sign in to [Sourcegraph Analytics](https://cody-analytics.sourcegraph.com). +- Sign in to [Sourcegraph Analytics](https://analytics.sourcegraph.com). ## Data export Sourcegraph Cloud Analytics also includes a CSV export option with key metrics like the number of searches, chats, autocomplete suggestions, completion acceptance rate (CAR %), and more. The data is split by user, day, client/editor, and programming language, perfect for automating retrieval and analyzing data in ways that make the most sense to your organization. + + +## Access Tokens + +For Sourcegraph Analytics, you can generate an access token for programmatic access. Tokens are long lived with an optional expiry and have the same permissions to access instance data as the user who created them. + +### Token management APIs + +Token management is currently only available via the Sourcegraph Analytics UI. +Authentication is done via the `cas` session cookie. + +- Sign in to [Sourcegraph Analytics](https://analytics.sourcegraph.com). +- Retrieve your session cookie, `cas`, from your browser's developer tools. +- Export as environment variable to use in the following commands: +```sh +$ export CAS_COOKIE="" +``` + +#### Token creation + +- Create the token by running the following command: +```sh +$ curl -X POST https://analytics.sourcegraph.com/api/service-access-tokens \ + -H "Content-Type: application/json" \ + -H "Cookie: cas=$CAS_COOKIE" \ + -d '{}' + +# Optionally include `displayName`, `expiresAt`, or both in the request body. +# If `expiresAt` is not provided, the token will never expire. +# -d '{"displayName": "My Analytics Token", "expiresAt": "2025-12-31T23:59:59Z"}' +``` +- The response will include the token ID, secret, creation date, and, if provided, display name and expiration date. +```json +// example response +{ + "id": "4cf96e80-d5f3-4af0-a28d-3c70ba97abb4", + "displayName": "My Analytics Token", + "secret": "sams_at_abcdefghijk", + "createdAt": "2025-05-28T12:00:00Z", + "expiresAt": "2025-12-31T23:59:59Z" +} +``` + +#### Token listing + +- List the tokens by running the following command: +```sh +$ curl -X GET https://analytics.sourcegraph.com/api/service-access-tokens \ + -H "Cookie: cas=$CAS_COOKIE" +``` +- The response will include the token ID, secret, creation date, and, if provided, display name and expiration date. +```json +// example response +{ + "tokens": [ + { + "id": "5a140b00-3a79-497d-bcfb-c1d2e3d8c747", + "displayName": "My Analytics Token", + "createdAt": "2025-05-27T12:00:00Z", + "expiresAt": "2025-05-27T13:00:00Z", + "isExpired": true + }, + { + "id": "eaf8a6f1-1302-43f6-a9ad-f9862d75e959", + "createdAt": "2025-05-28T12:30:00Z", + "expiresAt": "2025-05-28T13:30:00Z", + "isExpired": true + }, + { + "id": "d7df6636-99d0-4266-9f32-a2fb7ccbfcd5", + "displayName": "My Analytics Token 2", + "createdAt": "2025-05-28T15:00:00Z", + "isExpired": false + }, + { + "id": "8ea63000-a164-44ca-8834-bb71e9b788fb", + "createdAt": "2025-05-28T15:30:00Z", + "isExpired": false + } + ] +} +``` + +#### Token revocation + +- Revoke a token by running the following command: + - Replace `:id` with the token ID. +```sh +$ curl -X DELETE https://analytics.sourcegraph.com/api/service-access-tokens/:id \ + -H "Cookie: cas=$CAS_COOKIE" +``` + +> NOTE: There is no output from the revocation request. To verify that the token has been revoked, list the tokens and verify `isExpired` is `true`. diff --git a/docs/analytics/index.mdx b/docs/analytics/index.mdx index 817961fa3..459f280d6 100644 --- a/docs/analytics/index.mdx +++ b/docs/analytics/index.mdx @@ -7,7 +7,7 @@ This solution is available to: - [Sourcegraph Cloud](/cloud) customers - Self-hosted customers that have fully enabled usage telemetry, and that are running a supported version of Sourcegraph (5.9+) -[Sourcegraph Cloud](/cloud) customers can use our managed [cloud analytics service](https://cody-analytics.sourcegraph.com) for Cody and Code Search usage data. +[Sourcegraph Cloud](/cloud) customers can use our managed [cloud analytics service](https://analytics.sourcegraph.com) for Cody and Code Search usage data. Self-hosted customers can also use this service, but they must: - Upgrade to a supported version of Sourcegraph (5.9+) - Have fully enabled usage telemetry diff --git a/public/llms.txt b/public/llms.txt index 30645c425..96fc55723 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -35881,7 +35881,7 @@ Enterprise customers can use Sourcegraph Analytics to get a clear view of usage, ## Sourcegraph Cloud Analytics -[Sourcegraph Cloud](/cloud) customers can use our managed [cloud analytics service](https://cody-analytics.sourcegraph.com) for Cody and Code Search usage data. +[Sourcegraph Cloud](/cloud) customers can use our managed [cloud analytics service](https://analytics.sourcegraph.com) for Cody and Code Search usage data. Self-hosted customers can also use this service, but they must Upgrade to a supported version of Sourcegraph (5.9+) @@ -36005,7 +36005,7 @@ To enable Sourcegraph Analytics: - Create an account on [Sourcegraph Accounts](https://accounts.sourcegraph.com/), or find the email address associated with your existing account. - Contact your Sourcegraph Technical Advisor or point of contact (or email us at support@sourcegraph.com if you don't know your contact), provide them with the email address you used to register above and ask for access to Sourcegraph Analytics. - They will validate your account and link it to your Sourcegraph Enterprise instance's usage metrics. -- Sign in to [Sourcegraph Analytics](https://cody-analytics.sourcegraph.com). +- Sign in to [Sourcegraph Analytics](https://analytics.sourcegraph.com). ## Data export From acfdaf37a622c9c19e0c11378c414226cc0dcff7 Mon Sep 17 00:00:00 2001 From: James Cotter Date: Wed, 28 May 2025 22:09:10 +0100 Subject: [PATCH 02/14] feedback --- docs/analytics/cloud.mdx | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index 7ccfe4a6f..a242c0474 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -24,7 +24,7 @@ For Sourcegraph Analytics, you can generate an access token for programmatic acc ### Token management APIs -Token management is currently only available via the Sourcegraph Analytics UI. +Token management is currently only available via the Sourcegraph Analytics API. Authentication is done via the `cas` session cookie. - Sign in to [Sourcegraph Analytics](https://analytics.sourcegraph.com). @@ -36,7 +36,8 @@ $ export CAS_COOKIE="" #### Token creation -- Create the token by running the following command: +Create the token by running the following command: + ```sh $ curl -X POST https://analytics.sourcegraph.com/api/service-access-tokens \ -H "Content-Type: application/json" \ @@ -44,12 +45,13 @@ $ curl -X POST https://analytics.sourcegraph.com/api/service-access-tokens \ -d '{}' # Optionally include `displayName`, `expiresAt`, or both in the request body. -# If `expiresAt` is not provided, the token will never expire. +# If `expiresAt` is not provided, the token will never expire and must be revoked manually. # -d '{"displayName": "My Analytics Token", "expiresAt": "2025-12-31T23:59:59Z"}' ``` -- The response will include the token ID, secret, creation date, and, if provided, display name and expiration date. + +The response will include the token ID, secret, creation date, and, if provided, display name and expiration date. For example: + ```json -// example response { "id": "4cf96e80-d5f3-4af0-a28d-3c70ba97abb4", "displayName": "My Analytics Token", @@ -61,14 +63,14 @@ $ curl -X POST https://analytics.sourcegraph.com/api/service-access-tokens \ #### Token listing -- List the tokens by running the following command: +List the tokens by running the following command: ```sh -$ curl -X GET https://analytics.sourcegraph.com/api/service-access-tokens \ +curl -X GET https://analytics.sourcegraph.com/api/service-access-tokens \ -H "Cookie: cas=$CAS_COOKIE" ``` -- The response will include the token ID, secret, creation date, and, if provided, display name and expiration date. +Each token in the response will include the token ID, creation date, a boolean indicating if the token is expired, and if provided: display name and expiration date. For example: ```json -// example response + { "tokens": [ { @@ -101,10 +103,11 @@ $ curl -X GET https://analytics.sourcegraph.com/api/service-access-tokens \ #### Token revocation -- Revoke a token by running the following command: - - Replace `:id` with the token ID. +Revoke a token by running the following commands: ```sh -$ curl -X DELETE https://analytics.sourcegraph.com/api/service-access-tokens/:id \ +export TOKEN_ID="" + +curl -X DELETE https://analytics.sourcegraph.com/api/service-access-tokens/$TOKEN_ID \ -H "Cookie: cas=$CAS_COOKIE" ``` From 21c33ed4a99e79365d91d67978a42b756d41c2ac Mon Sep 17 00:00:00 2001 From: James Cotter Date: Wed, 28 May 2025 23:00:47 +0100 Subject: [PATCH 03/14] session cookie screenshot --- docs/analytics/cloud.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index a242c0474..f771d2604 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -29,6 +29,7 @@ Authentication is done via the `cas` session cookie. - Sign in to [Sourcegraph Analytics](https://analytics.sourcegraph.com). - Retrieve your session cookie, `cas`, from your browser's developer tools. +![Sourcegraph Analytics session cookie](https://storage.googleapis.com/sourcegraph-assets/Docs/analytics-cookie.png) - Export as environment variable to use in the following commands: ```sh $ export CAS_COOKIE="" From 702ed30929c4d8b23c6c678a18d3cfb7cc36e721 Mon Sep 17 00:00:00 2001 From: James Cotter <35706755+jac@users.noreply.github.com> Date: Thu, 29 May 2025 00:09:51 +0100 Subject: [PATCH 04/14] Update docs/analytics/cloud.mdx Co-authored-by: Robert Lin --- docs/analytics/cloud.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index f771d2604..8578d1ef4 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -25,7 +25,7 @@ For Sourcegraph Analytics, you can generate an access token for programmatic acc ### Token management APIs Token management is currently only available via the Sourcegraph Analytics API. -Authentication is done via the `cas` session cookie. +Authentication for token management APIs is done via the `cas` session cookie. - Sign in to [Sourcegraph Analytics](https://analytics.sourcegraph.com). - Retrieve your session cookie, `cas`, from your browser's developer tools. From bbb84f7d08016e664516122a70d1dce251daf06a Mon Sep 17 00:00:00 2001 From: James Cotter <35706755+jac@users.noreply.github.com> Date: Thu, 29 May 2025 00:09:57 +0100 Subject: [PATCH 05/14] Update docs/analytics/cloud.mdx Co-authored-by: Robert Lin --- docs/analytics/cloud.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index 8578d1ef4..57af49338 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -40,7 +40,7 @@ $ export CAS_COOKIE="" Create the token by running the following command: ```sh -$ curl -X POST https://analytics.sourcegraph.com/api/service-access-tokens \ +curl -X POST https://analytics.sourcegraph.com/api/service-access-tokens \ -H "Content-Type: application/json" \ -H "Cookie: cas=$CAS_COOKIE" \ -d '{}' From 43a93cc791d67dc431cbfe58d75218c181ef27e4 Mon Sep 17 00:00:00 2001 From: James Cotter <35706755+jac@users.noreply.github.com> Date: Thu, 29 May 2025 00:10:09 +0100 Subject: [PATCH 06/14] Update docs/analytics/cloud.mdx Co-authored-by: Robert Lin --- docs/analytics/cloud.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index 57af49338..a54824240 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -71,7 +71,6 @@ curl -X GET https://analytics.sourcegraph.com/api/service-access-tokens \ ``` Each token in the response will include the token ID, creation date, a boolean indicating if the token is expired, and if provided: display name and expiration date. For example: ```json - { "tokens": [ { From 0ffcbc8cef6b87948a97f4da1bb9e56245369b90 Mon Sep 17 00:00:00 2001 From: James Cotter <35706755+jac@users.noreply.github.com> Date: Thu, 29 May 2025 00:10:18 +0100 Subject: [PATCH 07/14] Update docs/analytics/cloud.mdx Co-authored-by: Robert Lin --- docs/analytics/cloud.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index a54824240..8d02922bc 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -30,7 +30,7 @@ Authentication for token management APIs is done via the `cas` session cookie. - Sign in to [Sourcegraph Analytics](https://analytics.sourcegraph.com). - Retrieve your session cookie, `cas`, from your browser's developer tools. ![Sourcegraph Analytics session cookie](https://storage.googleapis.com/sourcegraph-assets/Docs/analytics-cookie.png) -- Export as environment variable to use in the following commands: +- Export the cookie as an environment variable to use in the following commands: ```sh $ export CAS_COOKIE="" ``` From 2de3c9d7e07dcfe1f9c06b43eec92af6b07cbf56 Mon Sep 17 00:00:00 2001 From: James Cotter Date: Thu, 29 May 2025 00:12:24 +0100 Subject: [PATCH 08/14] remove $ --- docs/analytics/cloud.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index 8d02922bc..d80b90ce5 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -32,7 +32,7 @@ Authentication for token management APIs is done via the `cas` session cookie. ![Sourcegraph Analytics session cookie](https://storage.googleapis.com/sourcegraph-assets/Docs/analytics-cookie.png) - Export the cookie as an environment variable to use in the following commands: ```sh -$ export CAS_COOKIE="" +export CAS_COOKIE="" ``` #### Token creation From ef3379e76a194ccceac90c6e1ce39be188cc613f Mon Sep 17 00:00:00 2001 From: James Cotter Date: Thu, 29 May 2025 13:00:10 +0100 Subject: [PATCH 09/14] add instructions for using the api --- docs/analytics/cloud.mdx | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index d80b90ce5..74eed7df0 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -15,7 +15,7 @@ To enable Sourcegraph Analytics: ## Data export -Sourcegraph Cloud Analytics also includes a CSV export option with key metrics like the number of searches, chats, autocomplete suggestions, completion acceptance rate (CAR %), and more. The data is split by user, day, client/editor, and programming language, perfect for automating retrieval and analyzing data in ways that make the most sense to your organization. +Sourcegraph Analytics also includes a CSV export option with key metrics like the number of searches, chats, autocomplete suggestions, completion acceptance rate (CAR %), and more. The data is split by user, day, client/editor, and programming language, perfect for automating retrieval and analyzing data in ways that make the most sense to your organization. ## Access Tokens @@ -112,3 +112,36 @@ curl -X DELETE https://analytics.sourcegraph.com/api/service-access-tokens/$TOKE ``` > NOTE: There is no output from the revocation request. To verify that the token has been revoked, list the tokens and verify `isExpired` is `true`. + +## API Reference + +Sourcegraph Analytics API is a RESTful API that allows access to Sourcegraph Analytics data. For authenticating to the API follow the [token creation](#token-creation) instructions. + +Export your access token as en environment variable: +```sh +export ACCESS_TOKEN="" +``` + +### CSV Export + +To generate a CSV export of the data for a specific instance, run the following commands: +```sh +export INSTANCE_URL="" # e.g. example.sourcegraphcloud.com + +curl -X GET "https://analytics.sourcegraph.com/api/reports/by-user-client-date?instanceURL=$INSTANCE_URL" \ + -H "Authorization: Bearer $ACCESS_TOKEN" +``` + +Optional granularity values can be specified. If not specified the default is `by_user_day_client_language`. +- `by_user`, +- `by_user_month`, +- `by_user_day`, +- `by_user_day_client_language` + +```sh +export INSTANCE_URL="" # e.g. example.sourcegraphcloud.com +export GRANULARITY="" + +curl -X GET "https://analytics.sourcegraph.com/api/reports/by-user-client-date?instanceURL=$INSTANCE_URL&granularity=$GRANULARITY" \ + -H "Authorization: Bearer $ACCESS_TOKEN" +``` From caa2acc6885488137659a3e23ed566532e1591ea Mon Sep 17 00:00:00 2001 From: James Cotter Date: Thu, 29 May 2025 14:15:10 +0100 Subject: [PATCH 10/14] tweak --- docs/analytics/cloud.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index 74eed7df0..363be5f80 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -45,8 +45,8 @@ curl -X POST https://analytics.sourcegraph.com/api/service-access-tokens \ -H "Cookie: cas=$CAS_COOKIE" \ -d '{}' -# Optionally include `displayName`, `expiresAt`, or both in the request body. -# If `expiresAt` is not provided, the token will never expire and must be revoked manually. +# Optionally include displayName, expiresAt, or both in the request body. +# If expiresAt is not provided, the token will never expire and must be revoked manually. # -d '{"displayName": "My Analytics Token", "expiresAt": "2025-12-31T23:59:59Z"}' ``` From c5ab5abb0d86fbb92702dd3414c97fe8211da3f1 Mon Sep 17 00:00:00 2001 From: James Cotter <35706755+jac@users.noreply.github.com> Date: Thu, 29 May 2025 18:29:09 +0100 Subject: [PATCH 11/14] Update docs/analytics/cloud.mdx Co-authored-by: Robert Lin --- docs/analytics/cloud.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index 363be5f80..c39250849 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -18,7 +18,7 @@ To enable Sourcegraph Analytics: Sourcegraph Analytics also includes a CSV export option with key metrics like the number of searches, chats, autocomplete suggestions, completion acceptance rate (CAR %), and more. The data is split by user, day, client/editor, and programming language, perfect for automating retrieval and analyzing data in ways that make the most sense to your organization. -## Access Tokens +## Access tokens For Sourcegraph Analytics, you can generate an access token for programmatic access. Tokens are long lived with an optional expiry and have the same permissions to access instance data as the user who created them. From c8ecda5076300efc461a6c6b801004a972c5a112 Mon Sep 17 00:00:00 2001 From: James Cotter <35706755+jac@users.noreply.github.com> Date: Thu, 29 May 2025 18:29:43 +0100 Subject: [PATCH 12/14] Apply suggestions from code review Co-authored-by: Robert Lin --- docs/analytics/cloud.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index c39250849..59c59e32d 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -113,7 +113,7 @@ curl -X DELETE https://analytics.sourcegraph.com/api/service-access-tokens/$TOKE > NOTE: There is no output from the revocation request. To verify that the token has been revoked, list the tokens and verify `isExpired` is `true`. -## API Reference +## API reference Sourcegraph Analytics API is a RESTful API that allows access to Sourcegraph Analytics data. For authenticating to the API follow the [token creation](#token-creation) instructions. @@ -122,7 +122,7 @@ Export your access token as en environment variable: export ACCESS_TOKEN="" ``` -### CSV Export +### CSV export To generate a CSV export of the data for a specific instance, run the following commands: ```sh From 0e477e0865bdf3ca04d6f45bd11b4c0905b9a6a7 Mon Sep 17 00:00:00 2001 From: Maedah Batool Date: Thu, 29 May 2025 10:54:44 -0700 Subject: [PATCH 13/14] Add improvemets and callouts --- docs/analytics/cloud.mdx | 50 +++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 21 deletions(-) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index 59c59e32d..97eee1638 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -1,6 +1,6 @@ # Sourcegraph Cloud Analytics -The following instructions are for all Sourcegraph Cloud and self-hosted customers who have upgraded to a sufficient version of Sourcegraph (5.9+) and fully enabled usage telemetry. +The following instructions are for all Sourcegraph Cloud and self-hosted customers who have upgraded to a sufficient version of Sourcegraph (5.9+) and fully enabled usage telemetry. ![Sourcegraph-cloud-analytics](https://storage.googleapis.com/sourcegraph-assets/cloud-analytics.png) @@ -15,22 +15,23 @@ To enable Sourcegraph Analytics: ## Data export -Sourcegraph Analytics also includes a CSV export option with key metrics like the number of searches, chats, autocomplete suggestions, completion acceptance rate (CAR %), and more. The data is split by user, day, client/editor, and programming language, perfect for automating retrieval and analyzing data in ways that make the most sense to your organization. - +Sourcegraph Analytics also includes a CSV export option with key metrics like the number of searches, chats, autocomplete suggestions, Completion Acceptance Rate (CAR%), and more. The data is split by user, day, client/editor, and programming language, perfect for automating retrieval and analyzing data in ways that make the most sense to your organization. ## Access tokens -For Sourcegraph Analytics, you can generate an access token for programmatic access. Tokens are long lived with an optional expiry and have the same permissions to access instance data as the user who created them. +For Sourcegraph Analytics, you can generate an access token for programmatic access. Tokens are long-lived with an optional expiry and have the same permissions to access instance data as the user who created them. ### Token management APIs -Token management is currently only available via the Sourcegraph Analytics API. -Authentication for token management APIs is done via the `cas` session cookie. +Token management is currently only available via the Sourcegraph Analytics API. Token management APIs are authenticated via the `cas` session cookie. - Sign in to [Sourcegraph Analytics](https://analytics.sourcegraph.com). - Retrieve your session cookie, `cas`, from your browser's developer tools. + ![Sourcegraph Analytics session cookie](https://storage.googleapis.com/sourcegraph-assets/Docs/analytics-cookie.png) + - Export the cookie as an environment variable to use in the following commands: + ```sh export CAS_COOKIE="" ``` @@ -41,13 +42,13 @@ Create the token by running the following command: ```sh curl -X POST https://analytics.sourcegraph.com/api/service-access-tokens \ - -H "Content-Type: application/json" \ + -H "Content-Type: application/json" \ -H "Cookie: cas=$CAS_COOKIE" \ - -d '{}' + -d '{}' # Optionally include displayName, expiresAt, or both in the request body. # If expiresAt is not provided, the token will never expire and must be revoked manually. -# -d '{"displayName": "My Analytics Token", "expiresAt": "2025-12-31T23:59:59Z"}' +# -d '{"displayName": "My Analytics Token", "expiresAt": "2025-12-31T23:59:59Z"}' ``` The response will include the token ID, secret, creation date, and, if provided, display name and expiration date. For example: @@ -65,11 +66,14 @@ The response will include the token ID, secret, creation date, and, if provided, #### Token listing List the tokens by running the following command: + ```sh curl -X GET https://analytics.sourcegraph.com/api/service-access-tokens \ - -H "Cookie: cas=$CAS_COOKIE" + -H "Cookie: cas=$CAS_COOKIE" ``` -Each token in the response will include the token ID, creation date, a boolean indicating if the token is expired, and if provided: display name and expiration date. For example: + +Each token in the response will include the token ID, creation date, a boolean indicating if the token has expired, and display name and expiration date if provided. For example: + ```json { "tokens": [ @@ -104,20 +108,22 @@ Each token in the response will include the token ID, creation date, a boolean i #### Token revocation Revoke a token by running the following commands: + ```sh export TOKEN_ID="" curl -X DELETE https://analytics.sourcegraph.com/api/service-access-tokens/$TOKEN_ID \ - -H "Cookie: cas=$CAS_COOKIE" + -H "Cookie: cas=$CAS_COOKIE" ``` -> NOTE: There is no output from the revocation request. To verify that the token has been revoked, list the tokens and verify `isExpired` is `true`. +The revocation request does not produce output. To verify that a token has been revoked, list the tokens and verify that `isExpired` is `true`. ## API reference -Sourcegraph Analytics API is a RESTful API that allows access to Sourcegraph Analytics data. For authenticating to the API follow the [token creation](#token-creation) instructions. +Sourcegraph Analytics API is a RESTful API that allows access to Sourcegraph Analytics data. To authenticate to the API, follow the instructions for [token creation](#token-creation). + +Export your access token as an environment variable: -Export your access token as en environment variable: ```sh export ACCESS_TOKEN="" ``` @@ -125,17 +131,19 @@ export ACCESS_TOKEN="" ### CSV export To generate a CSV export of the data for a specific instance, run the following commands: + ```sh export INSTANCE_URL="" # e.g. example.sourcegraphcloud.com curl -X GET "https://analytics.sourcegraph.com/api/reports/by-user-client-date?instanceURL=$INSTANCE_URL" \ - -H "Authorization: Bearer $ACCESS_TOKEN" + -H "Authorization: Bearer $ACCESS_TOKEN" ``` -Optional granularity values can be specified. If not specified the default is `by_user_day_client_language`. -- `by_user`, -- `by_user_month`, -- `by_user_day`, +Optional granularity values can be specified. If not specified, the default is `by_user_day_client_language`. + +- `by_user`, +- `by_user_month`, +- `by_user_day`, - `by_user_day_client_language` ```sh @@ -143,5 +151,5 @@ export INSTANCE_URL="" # e.g. example.sourcegraphcloud.com export GRANULARITY="" curl -X GET "https://analytics.sourcegraph.com/api/reports/by-user-client-date?instanceURL=$INSTANCE_URL&granularity=$GRANULARITY" \ - -H "Authorization: Bearer $ACCESS_TOKEN" + -H "Authorization: Bearer $ACCESS_TOKEN" ``` From c81f64b1fddf40f8525d77766c946c0182c05b61 Mon Sep 17 00:00:00 2001 From: James Cotter Date: Thu, 29 May 2025 19:01:31 +0100 Subject: [PATCH 14/14] consistent indentation --- docs/analytics/cloud.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index 97eee1638..dc936ded0 100644 --- a/docs/analytics/cloud.mdx +++ b/docs/analytics/cloud.mdx @@ -43,7 +43,7 @@ Create the token by running the following command: ```sh curl -X POST https://analytics.sourcegraph.com/api/service-access-tokens \ -H "Content-Type: application/json" \ - -H "Cookie: cas=$CAS_COOKIE" \ + -H "Cookie: cas=$CAS_COOKIE" \ -d '{}' # Optionally include displayName, expiresAt, or both in the request body.