diff --git a/specs/cli/client-add.md b/specs/cli/client-add.md index 6f46ee464e..3e17b7fab6 100644 --- a/specs/cli/client-add.md +++ b/specs/cli/client-add.md @@ -14,24 +14,26 @@ Once the `kiota-config.json` file is generated and the OpenAPI description file ## Parameters -| Parameters | Required | Example | Description | -| -- | -- | -- | -- | -| `--client-name \| --cn` | Yes | GraphClient | Name of the client and the client class. Unique within the parent API. Defaults to `Client` | -| `--openapi \| -d` | Yes | https://aka.ms/graph/v1.0/openapi.yaml | The location of the OpenAPI description in JSON or YAML format to use to generate the SDK. Accepts a URL or a local path. | -| `--search-key \| --sk` | No | github::microsoftgraph/msgraph-metadata/graph.microsoft.com/v1.0 | The search key used to locate the OpenAPI description. | -| `--include-path \| -i` | No | /me/chats#GET | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | -| `--exclude-path \| -e` | No | \*\*/users/\*\* | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | -| `--language \| -l` | Yes | csharp | The target language for the generated code files or for the information. | -| `--namespace-name \| -n` | No | Contoso.GraphApp | The namespace of the client class. Defaults to `Microsoft.Graph`. | -| `--backing-store \| -b` | No | | Defaults to `false` | -| `--exclude-backward-compatible \| --ebc` | No | | Whether to exclude the code generated only for backward compatibility reasons or not. Defaults to `false`. | -| `--structured-media-types \| -m` | No | `application/json` |Any valid media type which will match a request body type or a response type in the OpenAPI description. Default are documented [here](https://learn.microsoft.com/en-us/openapi/kiota/using#--structured-mime-types--m). | -| `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | -| `--output \| -o` | No | ./generated/graph/csharp | The output directory or file path for the generated code files. This is relative to the location of `kiota-config.json`. Defaults to `./output`. | +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--client-name \| --cn` | Yes | graphDelegated | Name of the client and the client class. Unique within the parent API. Defaults to `Client` | No | +| `--openapi \| -d` | Yes | https://aka.ms/graph/v1.0/openapi.yaml | The location of the OpenAPI description in JSON or YAML format to use to generate the SDK. Accepts a URL or a local path. | No | +| `--search-key \| --sk` | No | github::microsoftgraph/msgraph-metadata/graph.microsoft.com/v1.0 | The search key used to locate the OpenAPI description. | Yes, without its value | +| `--include-path \| -i` | No | /me/chats#GET | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | Yes, without its value | +| `--exclude-path \| -e` | No | \*\*/users/\*\* | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value | +| `--language \| -l` | Yes | csharp | The target language for the generated code files or for the information. | Yes | +| `--namespace-name \| -n` | No | Contoso.GraphApp | The namespace of the client class. Defaults to `Microsoft.Graph`. | Yes, without its value | +| `--backing-store \| -b` | No | | Defaults to `false` | Yes | +| `--exclude-backward-compatible \| --ebc` | No | | Whether to exclude the code generated only for backward compatibility reasons or not. Defaults to `false`. | Yes | +| `--structured-media-types \| -m` | No | `application/json` | Any valid media type which will match a request body type or a response type in the OpenAPI description. Default are documented [here](https://learn.microsoft.com/en-us/openapi/kiota/using#--structured-mime-types--m). | Yes | +| `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. |Yes | +| `--output \| -o` | No | ./generated/graph/csharp | The output directory or file path for the generated code files. This is relative to the location of `kiota-config.json`. Defaults to `./output`. | Yes, without its value | > [!NOTE] > It is not required to use the CLI to add new clients. It is possible to add a new client by adding a new entry in the `clients` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json) for more information. Using `kiota client generate --client-name myClient` would be required to generate the code files. +## Telemetry + ## Using `kiota client add` ```bash diff --git a/specs/cli/client-edit.md b/specs/cli/client-edit.md index d1e4993283..edd6ceb3a6 100644 --- a/specs/cli/client-edit.md +++ b/specs/cli/client-edit.md @@ -10,19 +10,19 @@ Once the `kiota-config.json` file and the API Manifest are updated, the code gen ## Parameters -| Parameters | Required | Example | Description | -| -- | -- | -- | -- | -| `--client-name \| --cn` | Yes | GraphClient | Name of the client. Unique within the parent API. | -| `--openapi \| -d` | No | https://aka.ms/graph/v1.0/openapi.yaml | The location of the OpenAPI description in JSON or YAML format to use to generate the SDK. Accepts a URL or a local path. | -| `--include-path \| -i` | No | /me/chats#GET | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | -| `--exclude-path \| -e` | No | \*\*/users/\*\* | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | -| `--language \| -l` | No | csharp | The target language for the generated code files or for the information. | -| `--namespace-name \| -n` | No | Contoso.GraphApp | The namespace of the client class. Defaults to `Microsoft.Graph`. | -| `--backing-store \| -b` | No | | Defaults to `false` | -| `--exclude-backward-compatible \| --ebc` | No | | Whether to exclude the code generated only for backward compatibility reasons or not. Defaults to `false`. | -| `--structured-media-types \| -m` | No | `application/json` |Any valid media type which will match a request body type or a response type in the OpenAPI description. Default are documented [here](https://learn.microsoft.com/en-us/openapi/kiota/using#--structured-mime-types--m). | -| `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | -| `--output \| -o` | No | ./generated/graph/csharp | The output directory or file path for the generated code files. Defaults to `./output`. | +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--client-name \| --cn` | Yes | graphDelegated | Name of the client. Unique within the parent API. If not provided, defaults to --class-name or its default. | Yes, without its value | +| `--openapi \| -d` | No | https://aka.ms/graph/v1.0/openapi.yaml | The location of the OpenAPI description in JSON or YAML format to use to generate the SDK. Accepts a URL or a local path. | Yes, without its value | +| `--include-path \| -i` | No | /me/chats#GET | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | Yes, without its value | +| `--exclude-path \| -e` | No | \*\*/users/\*\* | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value | +| `--language \| -l` | No | csharp | The target language for the generated code files or for the information. | Yes | +| `--namespace-name \| -n` | No | Contoso.GraphApp | The namespace of the client class. Defaults to `Microsoft.Graph`. | Yes, without its value | +| `--backing-store \| -b` | No | | Defaults to `false` | Yes | +| `--exclude-backward-compatible \| --ebc` | No | | Whether to exclude the code generated only for backward compatibility reasons or not. Defaults to `false`. | Yes | +| `--structured-media-types \| -m` | No | `application/json` |Any valid media type which will match a request body type or a response type in the OpenAPI description. Default are documented [here](https://learn.microsoft.com/en-us/openapi/kiota/using#--structured-mime-types--m). | Yes | +| `--skip-generation \| --sg` | No | true | When specified, the generation would be skipped. Defaults to false. | Yes | +| `--output \| -o` | No | ./generated/graph/csharp | The output directory or file path for the generated code files. Defaults to `./output`. | Yes, without its value | > [!NOTE] > It is not required to use the CLI to edit clients. It is possible to edit a client by modifying its entry in the `clients` section of the `kiota-config.json` file. See the [kiota-config.json schema](../schemas/kiota-config.json.md) for more information. diff --git a/specs/cli/client-generate.md b/specs/cli/client-generate.md index 07d9dbffd9..84b93c1705 100644 --- a/specs/cli/client-generate.md +++ b/specs/cli/client-generate.md @@ -10,10 +10,10 @@ In general cases, the `kiota client generate` command will generate the code for ## Parameters -| Parameters | Required | Example | Description | -| -- | -- | -- | -- | -| `--client-name \| --cn` | No | GraphClient | Name of the client. Unique within the parent API. | -| `--refresh \| -r` | No | true | Provided when refreshing the description(s) is required. | +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--client-name \| --cn` | No | graphDelegated | Name of the client. Unique within the parent API. | Yes, without it's value | +| `--refresh \| -r` | No | true | Provided when refreshing the description(s) is required. | Yes | ## Usage diff --git a/specs/cli/client-remove.md b/specs/cli/client-remove.md index d76f3d911f..4ce0465b29 100644 --- a/specs/cli/client-remove.md +++ b/specs/cli/client-remove.md @@ -6,10 +6,10 @@ The command also has one optional parameter, the ability to remove the generated client. If provided, kiota will delete the folder and its content specified at the `outputPath` from the client configuration. It will also remove the local version of the OpenAPI description file (specified by the `x-ms-kiotaHash` property in the API Manifest). The API Manifest is also updated to remove the dependency from the list of dependencies. -| Parameters | Required | Example | Description | -| -- | -- | -- | -- | -| `--client-name \| --cn` | Yes | GraphClient | Name of the client | -| `--clean-output \| --co` | No | | Cleans the generated client | +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--client-name \| --cn` | Yes | graphDelegated | Name of the client | Yes, without its value | +| `--clean-output \| --co` | No | | Cleans the generated client | Yes | #### Using kiota client remove diff --git a/specs/cli/config-migrate.md b/specs/cli/config-migrate.md index 0992e3dcd8..cfd1aca484 100644 --- a/specs/cli/config-migrate.md +++ b/specs/cli/config-migrate.md @@ -6,10 +6,10 @@ In the case where conflicting API client names would be migrated, the command wi ## Parameters -| Parameters | Required | Example | Description | -| -- | -- | -- | -- | -| `--lock-location \| --ll` | No | ./output/pythonClient/kiota-lock.json | Location of the `kiota-lock.json` file. If not specified, all `kiota-lock.json` files within in the current directory tree will be used. | -| `--client-name \| --cn` | No | GraphClient | Used with `--lock-location`, it would allow to specify a name for the API client. Else, name is auto-generated as a concatenation of the `language` and `clientClassName`. | +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--lock-location` | No | ./output/pythonClient/kiota-lock.json | Location of the `kiota-lock.json` file. If not specified, all `kiota-lock.json` files within in the current directory tree will be used. | Yes, without its value | +| `--client-name \| --cn` | No | graphDelegated | Used with `--lock-location`, it would allow to specify a name for the API client. Else, name is auto-generated as a concatenation of the `language` and `clientClassName`. | Yes, without its value | ## Using `kiota config migrate` diff --git a/specs/cli/download.md b/specs/cli/download.md new file mode 100644 index 0000000000..fa1d9719fc --- /dev/null +++ b/specs/cli/download.md @@ -0,0 +1,22 @@ +# download + +## Description + +Downloads an API description. + +## Parameters + +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `search-term` | Yes | Graph | The term to search for. | Yes, without its value | +| `--clear-cache \| --cc` | No | true | Clears any cached data for the current command. Defaults to `False`. | Yes | +| `--clear-output \| --cc` | No | true | Delete the output directory before generating the client. Defaults to `False`. | Yes | +| `--log-level \| --ll` | No | Critical | The log level to use when logging messages to the main output. Options available: Critical, Debug, Error, Information, None, Trace & Warning. Defaults to `Warning`. | Yes | +| `--version \| --v` | No | beta | The version of the OpenAPI document to use | Yes, without its value | +| `--output \| --o` | No | beta | The output directory or file path for the generated code files. Defaults `./output/result.json`. | Yes, without its value | + +## Usage + +```bash +kiota download apisguru::github.com +``` \ No newline at end of file diff --git a/specs/cli/index.md b/specs/cli/index.md new file mode 100644 index 0000000000..413bc0932a --- /dev/null +++ b/specs/cli/index.md @@ -0,0 +1,16 @@ +# CLI Commands + +This section contains the specifications for the Kiota CLI commands. All the commands are documented here: + +* [kiota client add](./client-add.md) +* [kiota client edit](./client-edit.md) +* [kiota client remove](./client-remove.md) +* [kiota client generate](./client-generate.md) +* [kiota config init](./config-init.md) +* [kiota config migrate](./config-migrate.md) +* [kiota download](./download.md) +* [kiota info](./info.md) +* [kiota login](./login.md) +* [kiota logout](./logout.md) +* [kiota search](./search.md) +* [kiota show](./show.md) \ No newline at end of file diff --git a/specs/cli/info.md b/specs/cli/info.md new file mode 100644 index 0000000000..bb12f225e0 --- /dev/null +++ b/specs/cli/info.md @@ -0,0 +1,98 @@ +# info + +## Description + +Show languages and runtime dependencies information. + +## Parameters + +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--openapi \| -d` | Yes | https://aka.ms/graph/v1.0/openapi.yaml | The location of the OpenAPI description in JSON or YAML format to use to generate the SDK. Accepts a URL or a local path. | Yes, without its value | +| `--language \| -l` | No | csharp | The target language for the generated code files or for the information. | Yes | +| `--clear-cache \| --cc` | No | true | Clears any cached data for the current command. Defaults to `False`. | Yes | +| `--log-level \| --ll` | No | Critical | The log level to use when logging messages to the main output. Options available: Critical, Debug, Error, Information, None, Trace & Warning. Defaults to `Warning`. | Yes | +| `--version \| --v` | No | beta | The version of the OpenAPI document to use | Yes, without its value | +| `--search-key \| --k` | No | github::microsoftgraph/msgraph-metadata/graph.microsoft.com/v1.0 | The search key used to locate the OpenAPI description. | Yes, without its value | + +## Usage + +```bash +kiota info +``` + +```bash +Language Maturity Level +CLI Preview +CSharp Stable +Go Stable +Java Preview +PHP Stable +Python Stable +Ruby Experimental +Swift Experimental +TypeScript Experimental +``` + +The following command with the provided options will display the following result. + +```bash +kiota info -l CSharp +``` + +```bash +The language CSharp is currently in Stable maturity level. +After generating code for this language, you need to install the following packages: +dotnet add package Microsoft.Kiota.Abstractions --version 1.6.1 +dotnet add package Microsoft.Kiota.Http.HttpClientLibrary --version 1.3.0 +dotnet add package Microsoft.Kiota.Serialization.Form --version 1.1.0 +dotnet add package Microsoft.Kiota.Serialization.Json --version 1.1.1 +dotnet add package Microsoft.Kiota.Authentication.Azure --version 1.1.0 +dotnet add package Microsoft.Kiota.Serialization.Text --version 1.1.0 +dotnet add package Microsoft.Kiota.Serialization.Multipart --version 1.1.0 +``` + +Using the `--json` optional parameter render the output in a machine parsable format: + +```bash +kiota info -l CSharp --json +``` + +```json +{ + "maturityLevel": "Stable", + "dependencyInstallCommand": "dotnet add package {0} --version {1}", + "dependencies": [ + { + "name": "Microsoft.Kiota.Abstractions", + "version": "1.6.1" + }, + { + "name": "Microsoft.Kiota.Http.HttpClientLibrary", + "version": "1.2.0" + }, + { + "name": "Microsoft.Kiota.Serialization.Form", + "version": "1.1.0" + }, + { + "name": "Microsoft.Kiota.Serialization.Json", + "version": "1.1.1" + }, + { + "name": "Microsoft.Kiota.Authentication.Azure", + "version": "1.1.0" + }, + { + "name": "Microsoft.Kiota.Serialization.Text", + "version": "1.1.0" + }, + { + "name": "Microsoft.Kiota.Serialization.Multipart", + "version": "1.1.0" + } + ], + "clientClassName": "", + "clientNamespaceName": "" +} +``` \ No newline at end of file diff --git a/specs/cli/login.md b/specs/cli/login.md new file mode 100644 index 0000000000..e0db1af5d1 --- /dev/null +++ b/specs/cli/login.md @@ -0,0 +1,20 @@ +# login + +## Description + +Use `kiota login` to sign in to private repositories and search for/display/generate clients for private API descriptions. This command makes sub-commands available to sign in to specific authentication providers. + +## Parameters + +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `search-provider` | Yes | github | The search provided to login with. | Yes | +| `type` | Yes | device | The authentication strategy to use. | Yes | +| `--log-level \| --ll` | No | Critical | The log level to use when logging messages to the main output. Options available: Critical, Debug, Error, Information, None, Trace & Warning. Defaults to `Warning`. | Yes | +| `--pat` | No | PAT value | The PAT used to login | Yes, without its value | + +## Usage + +```bash +kiota login github device +``` \ No newline at end of file diff --git a/specs/cli/logout.md b/specs/cli/logout.md new file mode 100644 index 0000000000..5401eb9ac9 --- /dev/null +++ b/specs/cli/logout.md @@ -0,0 +1,18 @@ +# logout + +## Description + +Use kiota logout to logout from a private repository containing API descriptions. + +## Parameters + +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `search-provider` | Yes | github | The search provided to login with. | Yes | +| `--log-level \| --ll` | No | Critical | The log level to use when logging messages to the main output. Options available: Critical, Debug, Error, Information, None, Trace & Warning. Defaults to `Warning`. | Yes | + +## Usage + +```bash +kiota logout github +``` \ No newline at end of file diff --git a/specs/cli/search.md b/specs/cli/search.md new file mode 100644 index 0000000000..2da4697495 --- /dev/null +++ b/specs/cli/search.md @@ -0,0 +1,47 @@ +# search + +## Description + +Search for APIs and their description from various registries. + +## Parameters + +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `search-term` | Yes | github | The term to search for. | Yes, without its value | +| `--clear-cache \| --cc` | No | true | Clears any cached data for the current command. Defaults to `False`. | Yes | +| `--log-level \| --ll` | No | Critical | The log level to use when logging messages to the main output. Options available: Critical, Debug, Error, Information, None, Trace & Warning. Defaults to `Warning`. | Yes | +| `--version \| --v` | No | beta | The version of the OpenAPI document to use | Yes, without its value | + +## Usage + +```bash +kiota search github +``` + +```bash +Key Title Description Versions +apisguru::github.com GitHub v3 REST API GitHub's v3 REST API. 1.1.4 +apisguru::github.com:api.github.com GitHub v3 REST API GitHub's v3 REST API. 1.1.4 +apisguru::github.com:ghes-2.18 GitHub v3 REST API GitHub's v3 REST API. 1.1.4 +apisguru::github.com:ghes-2.19 GitHub v3 REST API GitHub's v3 REST API. 1.1.4 +apisguru::github.com:ghes-2.20 GitHub v3 REST API GitHub's v3 REST API. 1.1.4 +apisguru::github.com:ghes-2.21 GitHub v3 REST API GitHub's v3 REST API. 1.1.4 +apisguru::github.com:ghes-2.22 GitHub v3 REST API GitHub's v3 REST API. 1.1.4 +apisguru::github.com:ghes-3.0 GitHub v3 REST API GitHub's v3 REST API. 1.1.4 +apisguru::github.com:ghes-3.1 GitHub v3 REST API GitHub's v3 REST API. 1.1.4 +``` + +If the search term is an exact match with one of the results' key, the search command will display a detailed view of the result. + +```bash +kiota search apisguru::github.com +``` + +```bash +Key: apisguru::github.com +Title: GitHub v3 REST API +Description: GitHub's v3 REST API. +Service: https://support.github.com/contact +OpenAPI: https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json +``` \ No newline at end of file diff --git a/specs/cli/show.md b/specs/cli/show.md new file mode 100644 index 0000000000..ced7dbfe7f --- /dev/null +++ b/specs/cli/show.md @@ -0,0 +1,35 @@ +# show + +## Description + +Show the API paths tree for an API description. + +## Parameters + +| Parameters | Required | Example | Description | Telemetry | +| -- | -- | -- | -- | -- | +| `--openapi \| -d` | Yes | https://aka.ms/graph/v1.0/openapi.yaml | The location of the OpenAPI description in JSON or YAML format to use to generate the SDK. Accepts a URL or a local path. | Yes, without its value | +| `--clear-cache \| --cc` | No | true | Clears any cached data for the current command. Defaults to `False`. | Yes | +| `--log-level \| --ll` | No | Critical | The log level to use when logging messages to the main output. Options available: Critical, Debug, Error, Information, None, Trace & Warning. Defaults to `Warning`. | Yes | +| `--version \| --v` | No | beta | The version of the OpenAPI document to use | Yes, without its value | +| `--search-key \| --k` | No | github::microsoftgraph/msgraph-metadata/graph.microsoft.com/v1.0 | The search key used to locate the OpenAPI description. | Yes, without its value | +| `--max-depth \| --m-d` | No | 10 | The maximum depth of the tree to display. Defaults to `5`. | Yes, without its value | +| `--include-path \| -i` | No | /me/chats#GET | A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything. | Yes, without its value | +| `--exclude-path \| -e` | No | \*\*/users/\*\* | A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing. | Yes, without its value | + +## Usage + +```bash +kiota show -d https://aka.ms/graph/v1.0/openapi.yaml -i **/messages +``` + +```bash +/ + └─users + └─{user-id} + ├─mailFolders + │ └─{mailFolder-id} + │ ├─childFolders + │ └─messages + └─messages +``` \ No newline at end of file diff --git a/specs/index.md b/specs/index.md index 78579ac2b0..8c4afc475a 100644 --- a/specs/index.md +++ b/specs/index.md @@ -1,7 +1,6 @@ # Kiota Specification Repository This repository contains the specifications for the Kiota project. The goal of this repository is to provide a place to discuss and document the Kiota project. It will evolve over time as the project evolves. -config.md) ## CLI @@ -11,12 +10,19 @@ config.md) * [kiota client generate](./cli/client-generate.md) * [kiota config init](./cli/config-init.md) * [kiota config migrate](./cli/config-migrate.md) +* [kiota download](./cli/download.md) +* [kiota info](./cli/info.md) +* [kiota login](./cli/login.md) +* [kiota logout](./cli/logout.md) +* [kiota search](./cli/search.md) +* [kiota show](./cli/show.md) ## Extension ## Scenarios * [Kiota Config](./scenarios/kiota-config.md) +* [Telemetry](./scenarios/telemetry.md) ## Schemas diff --git a/specs/scenarios/telemetry.md b/specs/scenarios/telemetry.md new file mode 100644 index 0000000000..fad4f250b0 --- /dev/null +++ b/specs/scenarios/telemetry.md @@ -0,0 +1,93 @@ +# Telemetry + +Kiota is a tool that generates code for interacting with an API. It is used by developers to create applications that interact with an API. It is also used by API owners to create SDKs for their API. In both cases, it is important to understand how the tool is being used and what are the scenarios leveraged by our community. This document describes the telemetry we plan to collect and how we use it. + +## Current Challenges + +- Kiota doesn't have a telemetry component as part of its CLI experience. +- The Kiota team doesn't have visibility on how the tool is being used and what are the scenarios that are important to our community. +- When planning for future investments, the Kiota team doesn't have a way to prioritize scenarios based on their importance to our community. + +## Goals + +- Understand how Kiota is being used. +- Understand what scenarios are important to our community. +- Understand what are the preferred experiences for using Kiota. + +## Non-goals + +- We are not trying to collect any personally identifiable information. +- We are not trying to collect any information about the API being used. +- We are not trying to collect any information about the application using the API. +- We are not trying to collect any information during the runtime of the application. + +## Proposal + +We should introduce a new telemetry component to Kiota. This component should be enabled by default and should be able to be disabled by the user, in a very similar way that the `dotnet` CLI does (https://learn.microsoft.com/en-us/dotnet/core/tools/telemetry). The telemetry component should be able to collect information about the following scenarios: + +- Adoption of the CLI in general. +- Adoption of the different commands. +- Adoption of the different parameters for each command (without values that could be considered sensitive like the OpenAPI description, include / exclude paths, etc.). +- Adoption of the different languages. +- Adoption of the different platforms we offer support for. + +### Privacy + +We should be very careful about the information we collect. Before rolling out this feature, we should have full agreement with CELA on our approach, the way we collect and protect the data. In general: + +- We should offer a way to opt-out of the telemetry collection. +- We should not collect any information that could be considered sensitive. +- We should not collect any information that could be used to identify a person, an application, or an API. +- We should not collect any information during the runtime of the application. + +### Examples of questions we want to answer + +- How many users are using the CLI? +- How many users are using the CLI via the extension? +- What is the current growth trajectory of the usage of kiota? +- What are the most used commands? +- How are the commands used? Which parameters are being used? +- What are the most used languages? +- What are the most used platforms? +- Is there a difference in how the CLI is being used between platforms? +- Do we have users using old versions of kiota? Why? +- When launching new capabilities, what is the adoption rate? How long does it take for users to adopt the new capabilities? +- Can we identify a spike in error being returned by Kiota? What is the impact of the error? What command generates the error? What parameters are being used? + +### Data collected + +#### Basic data being collected + +For every command, we should collect the following information: + +- Timestamp +- Operating system +- Operating system version +- Source (CLI or extension) +- Acquisition channel (dotnet tool, binaries, homebrew, asdf, extension, etc.) +- Kiota version +- VS Code extension version (if applicable) +- Command name +- Command parameters being used (without their values) +- Command execution time +- Command result (success or failure) + +#### Command-specific data being collected + +Every command has a different set of parameters. We should collect relevant parameters (and their values) for each command. The data collected shouldn't include any information that could be considered sensitive, only system-related information. Each command specification should include the list of parameters that should be collected and whether their values should be collected or not. + +The list of commands and their parameters can be found in the [CLI Commands](../cli/index.md) section. Each parameter indicates whether its value should be collected or not. + +### Opting-out + +We should offer a way to opt-out of the telemetry collection. This should be done in a very similar way that the `dotnet` CLI does (https://learn.microsoft.com/en-us/dotnet/core/tools/telemetry). To opt out of the telemetry feature, set the KIOTA_CLI_TELEMETRY_OPTOUT environment variable to 1 or true. + +Every time the CLI is installed and updated, we should inform the user about the telemetry feature and how to opt-out of it. If the users already opted-out, we should not inform the user and respect their choice. + +```bash +Telemetry +--------- +Kiota collect usage data in order to help us improve your experience. You can opt-out of telemetry by setting the KIOTA_CLI_TELEMETRY_OPTOUT environment variable to '1' or 'true' using your favorite shell. + +Read more about Kiota telemetry: https://aka.ms/kiota/docs/telemetry +``` \ No newline at end of file