diff --git a/docs/analytics/cloud.mdx b/docs/analytics/cloud.mdx index 5f3ca4397..dc936ded0 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) @@ -11,8 +11,145 @@ 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. +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. + +### Token management APIs + +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="" +``` + +#### 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 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. For example: + +```json +{ + "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" +``` + +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": [ + { + "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 commands: + +```sh +export TOKEN_ID="" + +curl -X DELETE https://analytics.sourcegraph.com/api/service-access-tokens/$TOKEN_ID \ + -H "Cookie: cas=$CAS_COOKIE" +``` + +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. To authenticate to the API, follow the instructions for [token creation](#token-creation). + +Export your access token as an 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" +``` 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