diff --git a/.gitignore b/.gitignore index 86ce0f3..461c294 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,2 @@ -# Claude Code settings .claude/ +.package-lock.json diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 8d25348..89d3ad5 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -4,5 +4,14 @@ title: "Introduction" The following is a list of publicly available APIs you can use with the [Traceloop platform](https://app.traceloop.com). -All APIs require an API key to be used. You can get one by [signing up](https://app.traceloop.com), -and then going to the [API Keys](https://app.traceloop.com/settings/api-keys) page. +All APIs require an API key to be used for authentication. + + + **To generate an API key:** + 1. [Sign up](https://app.traceloop.com) for a Traceloop account if you haven't already + 2. Go to [Settings → Organization](https://app.traceloop.com/settings/api-keys) + 3. Select a project and environment + 4. Click **Generate API key** and copy it immediately + + [Detailed instructions →](/settings/managing-api-keys) + diff --git a/datasets/sdk-usage.mdx b/datasets/sdk-usage.mdx index fff3f86..a64423f 100644 --- a/datasets/sdk-usage.mdx +++ b/datasets/sdk-usage.mdx @@ -37,9 +37,8 @@ const client = traceloop.getClient(); - Make sure you've created an API key and set it as an environment variable - `TRACELOOP_API_KEY` before you start. Check out the SDK's [getting started - guide](/openllmetry/getting-started-python) for more information. + **Prerequisites:** You need an API key set as the environment variable `TRACELOOP_API_KEY`. + [Generate one in Settings →](/settings/managing-api-keys) The SDK fetches your datasets from Traceloop servers. Changes made to a draft dataset version are immediately available in the UI. diff --git a/experiments/running-from-code.mdx b/experiments/running-from-code.mdx index 01ae5bb..d670111 100644 --- a/experiments/running-from-code.mdx +++ b/experiments/running-from-code.mdx @@ -39,9 +39,8 @@ const client = traceloop.getClient(); - Make sure you've created an API key and set it as an environment variable - `TRACELOOP_API_KEY` before you start. Check out the SDK's [getting started - guide](/openllmetry/getting-started-python) for more information. + **Prerequisites:** You need an API key set as the environment variable `TRACELOOP_API_KEY`. + [Generate one in Settings →](/settings/managing-api-keys) diff --git a/img/settings/project-dark.png b/img/settings/project-dark.png new file mode 100644 index 0000000..b26ba06 Binary files /dev/null and b/img/settings/project-dark.png differ diff --git a/img/settings/project-light.png b/img/settings/project-light.png new file mode 100644 index 0000000..5466914 Binary files /dev/null and b/img/settings/project-light.png differ diff --git a/img/settings/projects-dark.png b/img/settings/projects-dark.png new file mode 100644 index 0000000..c2f3465 Binary files /dev/null and b/img/settings/projects-dark.png differ diff --git a/img/settings/projects-light.png b/img/settings/projects-light.png new file mode 100644 index 0000000..cf3fe90 Binary files /dev/null and b/img/settings/projects-light.png differ diff --git a/mint.json b/mint.json index 34b9d61..3cf3c15 100644 --- a/mint.json +++ b/mint.json @@ -178,6 +178,13 @@ "group": "Prompt Management", "pages": ["prompts/quick-start", "prompts/registry", "prompts/sdk-usage"] }, + { + "group": "Settings", + "pages": [ + "settings/managing-api-keys", + "settings/projects-and-environments" + ] + }, { "group": "Integrations", "pages": ["integrations/posthog"] diff --git a/openllmetry/getting-started-go.mdx b/openllmetry/getting-started-go.mdx index 96e8d67..6f0b948 100644 --- a/openllmetry/getting-started-go.mdx +++ b/openllmetry/getting-started-go.mdx @@ -109,21 +109,29 @@ For Traceloop, read on. For other options, see [Exporting](/openllmetry/integrat ### Using Traceloop Cloud -Go to [Traceloop](https://app.traceloop.com), and create a new account. -Then, click on **Environments** on the left-hand navigation bar. Or go to directly to https://app.traceloop.com/settings/api-keys. -Click **Generate API Key** to generate an API key for the developement environment and click **Copy API Key** to copy it over. + + You need an API key to send traces to Traceloop. + [Generate one in Settings](https://app.traceloop.com/settings/api-keys) by selecting + a project and environment, then click **Generate API key**. -Make sure to copy it as it won't be shown again. + ⚠️ **Important:** Copy the key immediately - it won't be shown again after you close or reload the page. - - - - + [Detailed instructions →](/settings/managing-api-keys) + + +Set the API key as an environment variable in your app named `TRACELOOP_API_KEY`: -Set the copied Traceloop's API key as an environment variable in your app named `TRACELOOP_API_KEY`. +```bash +export TRACELOOP_API_KEY=your_api_key_here +``` Done! You'll get instant visibility into everything that's happening with your LLM. If you're calling a vector DB, or any other external service or database, you'll also see it in the Traceloop dashboard. + + **Not seeing traces?** Make sure you're viewing the correct project and environment in the + dashboard that matches your API key. See [Troubleshooting](/settings/managing-api-keys#troubleshooting). + + diff --git a/openllmetry/getting-started-nextjs.mdx b/openllmetry/getting-started-nextjs.mdx index 31ba6df..5b27277 100644 --- a/openllmetry/getting-started-nextjs.mdx +++ b/openllmetry/getting-started-nextjs.mdx @@ -208,21 +208,29 @@ For Traceloop, read on. For other options, see [Exporting](/openllmetry/integrat ### Using Traceloop Cloud -Go to [Traceloop](https://app.traceloop.com), and create a new account. -Then, click on **Environments** on the left-hand navigation bar. Or go to directly to https://app.traceloop.com/settings/api-keys. -Click **Generate API Key** to generate an API key for the developement environment and click **Copy API Key** to copy it over. + + You need an API key to send traces to Traceloop. + [Generate one in Settings](https://app.traceloop.com/settings/api-keys) by selecting + a project and environment, then click **Generate API key**. -Make sure to copy it as it won't be shown again. + ⚠️ **Important:** Copy the key immediately - it won't be shown again after you close or reload the page. - - - - + [Detailed instructions →](/settings/managing-api-keys) + -Set the copied Traceloop's API key as an environment variable in your app named `TRACELOOP_API_KEY`. +Set the API key as an environment variable in your app named `TRACELOOP_API_KEY`: + +```bash +export TRACELOOP_API_KEY=your_api_key_here +``` Done! You'll get instant visibility into everything that's happening with your LLM. If you're calling a vector DB, or any other external service or database, you'll also see it in the Traceloop dashboard. + + **Not seeing traces?** Make sure you're viewing the correct project and environment in the + dashboard that matches your API key. See [Troubleshooting](/settings/managing-api-keys#troubleshooting). + + diff --git a/openllmetry/getting-started-python.mdx b/openllmetry/getting-started-python.mdx index 577932b..735d81a 100644 --- a/openllmetry/getting-started-python.mdx +++ b/openllmetry/getting-started-python.mdx @@ -86,21 +86,29 @@ For Traceloop, read on. For other options, see [Exporting](/openllmetry/integrat ### Using Traceloop Cloud -Go to [Traceloop](https://app.traceloop.com), and create a new account. -Then, click on **Environments** on the left-hand navigation bar. Or go to directly to https://app.traceloop.com/settings/api-keys. -Click **Generate API Key** to generate an API key for the developement environment and click **Copy API Key** to copy it over. + + You need an API key to send traces to Traceloop. + [Generate one in Settings](https://app.traceloop.com/settings/api-keys) by selecting + a project and environment, then click **Generate API key**. -Make sure to copy it as it won't be shown again. + ⚠️ **Important:** Copy the key immediately - it won't be shown again after you close or reload the page. - - - - + [Detailed instructions →](/settings/managing-api-keys) + -Set the copied Traceloop's API key as an environment variable in your app named `TRACELOOP_API_KEY`. +Set the API key as an environment variable in your app named `TRACELOOP_API_KEY`: + +```bash +export TRACELOOP_API_KEY=your_api_key_here +``` Done! You'll get instant visibility into everything that's happening with your LLM. If you're calling a vector DB, or any other external service or database, you'll also see it in the Traceloop dashboard. + + **Not seeing traces?** Make sure you're viewing the correct project and environment in the + dashboard that matches your API key. See [Troubleshooting](/settings/managing-api-keys#troubleshooting). + + diff --git a/openllmetry/getting-started-ruby.mdx b/openllmetry/getting-started-ruby.mdx index e672b0b..86269f0 100644 --- a/openllmetry/getting-started-ruby.mdx +++ b/openllmetry/getting-started-ruby.mdx @@ -80,21 +80,29 @@ For Traceloop, read on. For other options, see [Exporting](/openllmetry/integrat ### Using Traceloop Cloud -Go to [Traceloop](https://app.traceloop.com), and create a new account. -Then, click on **Environments** on the left-hand navigation bar. Or go to directly to https://app.traceloop.com/settings/api-keys. -Click **Generate API Key** to generate an API key for the developement environment and click **Copy API Key** to copy it over. + + You need an API key to send traces to Traceloop. + [Generate one in Settings](https://app.traceloop.com/settings/api-keys) by selecting + a project and environment, then click **Generate API key**. -Make sure to copy it as it won't be shown again. + ⚠️ **Important:** Copy the key immediately - it won't be shown again after you close or reload the page. - - - - + [Detailed instructions →](/settings/managing-api-keys) + -Set the copied Traceloop's API key as an environment variable in your app named `TRACELOOP_API_KEY`. +Set the API key as an environment variable in your app named `TRACELOOP_API_KEY`: + +```bash +export TRACELOOP_API_KEY=your_api_key_here +``` Done! You'll get instant visibility into everything that's happening with your LLM. If you're calling a vector DB, or any other external service or database, you'll also see it in the Traceloop dashboard. + + **Not seeing traces?** Make sure you're viewing the correct project and environment in the + dashboard that matches your API key. See [Troubleshooting](/settings/managing-api-keys#troubleshooting). + + diff --git a/openllmetry/getting-started-ts.mdx b/openllmetry/getting-started-ts.mdx index 14309b8..43404dc 100644 --- a/openllmetry/getting-started-ts.mdx +++ b/openllmetry/getting-started-ts.mdx @@ -106,21 +106,29 @@ For Traceloop, read on. For other options, see [Exporting](/openllmetry/integrat ### Using Traceloop Cloud -Go to [Traceloop](https://app.traceloop.com), and create a new account. -Then, click on **Environments** on the left-hand navigation bar. Or go to directly to https://app.traceloop.com/settings/api-keys. -Click **Generate API Key** to generate an API key for the development environment and click **Copy API Key** to copy it over. + + You need an API key to send traces to Traceloop. + [Generate one in Settings](https://app.traceloop.com/settings/api-keys) by selecting + a project and environment, then click **Generate API key**. -Make sure to copy it as it won't be shown again. + ⚠️ **Important:** Copy the key immediately - it won't be shown again after you close or reload the page. - - - - + [Detailed instructions →](/settings/managing-api-keys) + -Set the copied Traceloop's API key as an environment variable in your app named `TRACELOOP_API_KEY`. +Set the API key as an environment variable in your app named `TRACELOOP_API_KEY`: + +```bash +export TRACELOOP_API_KEY=your_api_key_here +``` Done! You'll get instant visibility into everything that's happening with your LLM. If you're calling a vector DB, or any other external service or database, you'll also see it in the Traceloop dashboard. + + **Not seeing traces?** Make sure you're viewing the correct project and environment in the + dashboard that matches your API key. See [Troubleshooting](/settings/managing-api-keys#troubleshooting). + + diff --git a/openllmetry/integrations/traceloop.mdx b/openllmetry/integrations/traceloop.mdx index 05a6140..ccea989 100644 --- a/openllmetry/integrations/traceloop.mdx +++ b/openllmetry/integrations/traceloop.mdx @@ -13,23 +13,33 @@ It allows you to deploy changes to prompts and model configurations with confide ## Connecting OpenLLMetry to Traceloop directly -On Traceloop, API keys can be generated from the [Traceloop Dashboard](https://app.traceloop.com/settings/api-keys), for each of the three supported environments (Development, Staging, Production). + + You need an API key to send traces to Traceloop. API keys are scoped to a specific **project** and **environment**. -Go to [Traceloop Environments Management](https://app.traceloop.com/settings/api-keys) -(you can also reach here by clicking on **Environments** on the left-hand navigation bar). -Click on **Generate API Key**. Click **Copy Key** to copy the API key. + **To generate an API key:** + 1. Go to [Settings → Organization](https://app.traceloop.com/settings/api-keys) + 2. Click on your project (or create a new one) + 3. Select an environment (Development, Staging, Production, or custom) + 4. Click **Generate API key** + 5. **Copy the key immediately** - it won't be shown again after you close or reload the page - - API Keys are only displayed once, at the time of their creation and are not - stored anywhere. If you lose your API key, you will need to revoke the old one - and generate a new one. + [Detailed instructions →](/settings/managing-api-keys) -Set the API key as an environment variable named `TRACELOOP_API_KEY`. +Set the API key as an environment variable named `TRACELOOP_API_KEY`: + +```bash +export TRACELOOP_API_KEY=your_api_key_here +``` Done! You'll get instant visibility into everything that's happening with your LLM. If you're calling a vector DB, or any other external service or database, you'll also see it in the Traceloop dashboard. + + **Want to organize your data?** Learn about [Projects and Environments](/settings/projects-and-environments) + to separate traces for different applications and deployment stages. + + ## Using an OpenTelemetry Collector If you are using an [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/), you can route metrics and traces to Traceloop by simply adding an OTLP exporter to your collector configuration. diff --git a/prompts/quick-start.mdx b/prompts/quick-start.mdx index 75549b8..844dd54 100644 --- a/prompts/quick-start.mdx +++ b/prompts/quick-start.mdx @@ -14,9 +14,8 @@ You can use Traceloop to manage your prompts and model configurations. That way you can easily experiment with different prompts, and rollout changes gradually and safely. - Make sure you've created an API key and set it as an environment variable - `TRACELOOP_API_KEY` before you start. Check out the SDK's [getting started - guide](/openllmetry/getting-started-python) for more information. + **Prerequisites:** You need an API key set as the environment variable `TRACELOOP_API_KEY`. + [Generate one in Settings →](/settings/managing-api-keys) @@ -46,9 +45,6 @@ For more information see the [Registry Documentation](/prompts/registry). -If you haven't done so, make sure to [generate an API key](https://app.traceloop.com/settings/api-keys) and -set it as an environment variable `TRACELOOP_API_KEY`. - Make sure to initialize the SDK and enable traceloop sync (see below). On Typescript/Javascript, you should also wait for the initialization to diff --git a/settings/managing-api-keys.mdx b/settings/managing-api-keys.mdx new file mode 100644 index 0000000..8116f4c --- /dev/null +++ b/settings/managing-api-keys.mdx @@ -0,0 +1,249 @@ +--- +title: "Managing API Keys" +description: "Generate and manage API keys for sending traces and accessing Traceloop features" +--- + +API keys are required to authenticate your application with Traceloop. Each API key is tied to a specific project and environment combination, determining where your traces and data will appear. + + + + + + +## Quick Start: Generate Your First API Key + + + +Go to [Settings → Organization](https://app.traceloop.com/settings/api-keys) in your Traceloop dashboard. + + + +Click on the project where you want to generate an API key (e.g., "Default project"). + +If you haven't created a project yet, see [Projects and Environments](/settings/projects-and-environments). + + + +Find the environment you want to use (dev, stg, or prd) and click **Generate API key**. + + + **Copy the API key immediately!** The full key is only shown once and cannot be retrieved later. + After you close or reload the page, you'll need to revoke and generate a new key if you lose it. + + +The key will be displayed partially masked, but you can copy the full key using the copy button. + + + +Export the API key in your application: + +```bash +export TRACELOOP_API_KEY=your_api_key_here +``` + +Or set it in your `.env` file: + +```bash +TRACELOOP_API_KEY=your_api_key_here +``` + + + +Done! Your application can now send traces and access Traceloop features. + +## Understanding API Keys + +### How API Keys Work + +Each API key is scoped to a specific **project + environment** combination: +- **Project**: Isolates data for different applications or teams (e.g., "orders-service", "users-service") +- **Environment**: Separates deployment stages (dev, stg, prd) + +When you use an API key, Traceloop automatically knows where to save your data based on the key itself. + + + If the `TRACELOOP_API_KEY` environment variable is set, the SDK will automatically use it. You don't need to pass it explicitly in your code. + + +**Example:** +- API key from "web-app" → "dev" sends traces to the "web-app" project's dev environment +- API key from "api-service" → "prd" sends traces to the "api-service" project's prd environment + +### Viewing Your Data + +To see your traces in the dashboard: +1. Select the correct **project** from the project dropdown +2. Filter by **environment** if needed + + + **Not seeing your traces?** Make sure you're viewing the same project and environment + that matches your API key. + + +## Common Scenarios + +### Local Development + +Use your dev environment API key: + +```bash +# In your .env or shell +export TRACELOOP_API_KEY=your_development_key +``` + +### CI/CD Pipeline + +Use stg or prd keys in your deployment configuration: + +```yaml +# Example: GitHub Actions +env: + TRACELOOP_API_KEY: ${{ secrets.TRACELOOP_STG_KEY }} +``` + +```yaml +# Example: Docker Compose +environment: + - TRACELOOP_API_KEY=${TRACELOOP_PRD_KEY} +``` + +### Multiple Projects from One Application + +If you need to send data to different projects from the same codebase, pass the API key directly in code instead of using environment variables: + + +```python Python +from traceloop.sdk import Traceloop + +# Initialize with specific API key +Traceloop.init(api_key="your_project_specific_key") +``` + +```javascript TypeScript / JavaScript +import * as traceloop from "@traceloop/node-server-sdk"; + +// Initialize with specific API key +traceloop.initialize({ + apiKey: "your_project_specific_key" +}); +``` + +```go Go +import "github.com/traceloop/go-sdk/traceloop" + +// Initialize with specific API key +traceloop.Init(traceloop.Config{ + APIKey: "your_project_specific_key", +}) +``` + + +## Managing Your API Keys + +### Revoking an API Key + +If your API key is compromised or you need to rotate keys: + +1. Go to Settings → Organization → Select your project +2. Find the environment with the key you want to revoke +3. Click **Revoke API key** +4. Generate a new key immediately +5. Update your application configuration with the new key + + + Revoking a key immediately stops all applications using it from sending data. + Make sure to update your configuration before revoking production keys. + + +### Lost Your API Key? + +If you lose your API key and didn't save it: + +1. You **cannot** retrieve the original key +2. You must **revoke** the old key and **generate** a new one +3. Update your application with the new key + +This is a security feature - API keys are never stored in retrievable form. + +### Best Practices + + + + Store API keys in secret management systems like AWS Secrets Manager, Azure Key Vault, + HashiCorp Vault, or 1Password instead of hardcoding them. + + + + Periodically rotate your API keys, especially for production environments. + Schedule key rotation as part of your security practices. + + + + Never use prd API keys in dev or stg. + This prevents accidental data mixing and security risks. + + + + Don't commit API keys to version control. Use environment variables + or secret management systems instead. + + + +## Troubleshooting + +### Authentication Failed + +**Problem:** Getting authentication errors when initializing the SDK. + +**Solutions:** +- Verify the API key is correctly set as `TRACELOOP_API_KEY` +- Check if the key has been revoked (generate a new one if needed) +- Ensure there are no extra spaces or characters in the key + +### Not Seeing Traces + +**Problem:** Application runs but traces don't appear in dashboard. + +**Solutions:** +- Confirm you're viewing the correct **project** in the dashboard dropdown +- Check you're filtering by the correct **environment** +- Verify the API key matches the project + environment you're viewing +- Check SDK initialization logs for connection errors + +### Wrong Data Appearing + +**Problem:** Seeing unexpected traces or data in your project. + +**Solutions:** +- Double-check which API key you're using (`echo $TRACELOOP_API_KEY`) +- Verify the API key belongs to the intended project + environment +- Check if other team members are using the same project + +### Multiple Applications Sending to Same Project + +**Problem:** Want to separate data from different services but they're in the same project. + +**Solutions:** +- Create a separate project for each application/service +- Generate unique API keys for each project +- See [Projects and Environments](/settings/projects-and-environments) for more details + +## Related Resources + + + + Learn about organizing your applications and deployment stages + + + + Set up OpenLLMetry SDK with your API key + + + + Use API keys to access Traceloop's REST API + + + + Configure API keys in self-hosted deployments + + diff --git a/settings/projects-and-environments.mdx b/settings/projects-and-environments.mdx new file mode 100644 index 0000000..2104d79 --- /dev/null +++ b/settings/projects-and-environments.mdx @@ -0,0 +1,453 @@ +--- +title: "Projects and Environments" +description: "Organize your applications and deployment stages with Projects and Environments" +--- + +Projects and Environments help you keep your LLM observability data organized and isolated across different applications, services, and deployment stages. + + + + + + +## Why Projects and Environments? + +### The Problem + +When you have multiple applications or deployment stages: +- Traces from different services get mixed together +- Production data appears alongside development experiments +- Team members see irrelevant data from other projects +- Testing changes risks affecting production monitoring + +### The Solution + +**Projects** completely isolate data for different applications: +- Each project has its own traces, datasets, prompts, evaluators, and experiments +- Switch between projects to view specific application data +- Generate separate API keys per project + +**Environments** separate deployment stages within a project: +- dev, stg, and prd environments (built-in) +- Custom environments (e.g., "qa", "eu-prd", "preview") +- Each environment has its own API key and data stream + +## Understanding Projects + +### What is a Project? + +A project is a complete isolation boundary for all your Traceloop data. Think of it as a workspace for a specific application or service. + +**Each project contains:** +- Traces and spans +- Datasets for experiments +- Prompt configurations +- Evaluators and monitors +- Experiment results + +**Common use cases for creating projects:** +- Separate applications (e.g., "web-app", "mobile-app", "api-service") +- Microservices in a distributed system +- Different teams or product areas +- Major feature branches or product lines + +### When to Create a New Project + +✅ **Create a new project when:** +- Building a new application or service +- Separating data for different teams +- Testing major architectural changes in isolation +- Managing multi-tenant applications (one project per tenant) + +❌ **Don't create a new project for:** +- Different deployment stages (use environments instead) +- Temporary experiments (use Development environment) +- A/B tests (use datasets and experiments features) + +## Understanding Environments + +### What is an Environment? + +An environment represents a deployment stage within a project. Each environment has its own API key, allowing you to send traces from different stages without mixing the data. + +**Default environments** (cannot be deleted): +- **dev**: Local development and testing +- **stg**: Pre-production testing and validation +- **prd**: Live production traffic + +**Custom environments**: Add your own based on your workflow +- Examples: "qa", "uat", "preview", "eu-prd", "us-prd" + +### Organization-Level vs. Project-Level Environments + +Traceloop supports two types of environments: + +**Organization-Level Environments** +- Created at the organization settings level +- Automatically cascade to **all projects** (existing and new) +- Use this for environments that apply across your entire organization + +**Project-Specific Environments** +- Created within a single project +- Only appear in that specific project +- Use this for project-specific deployment stages + + + **Best practice:** Create organization-level environments for company-wide deployment stages + (dev, stg, prd, qa). Create project-specific environments only when needed + for unique deployment scenarios. + + +### How Environment Cascading Works + +When you create an organization-level environment: +1. It immediately appears in all existing projects +2. It automatically appears in any new projects you create +3. Each project can independently generate API keys for that environment + +**Example:** +``` +Organization creates "QA" environment + ↓ +Appears in "web-app" project (can generate its own QA API key) +Appears in "api-service" project (can generate its own QA API key) +Appears in "mobile-app" project (can generate its own QA API key) +``` + +## Setting Up Projects and Environments + + + +Go to **Settings** in your Traceloop dashboard, then select the **Organization** tab. + +You'll see two sections: +- **Projects and API keys**: Manage your projects +- **Organization environments**: Manage org-wide environments + + + +If you need a new project: + +1. Click the **+** button next to "Projects and API keys" +2. Enter a descriptive name (e.g., "web-app", "payment-service", "mobile-app") +3. Click **Create** + +The project is created instantly with all organization-level environments included. + + + A "Default project" is created automatically when you sign up. + You can rename or delete it if needed. + + + + +If you need additional environments beyond dev, stg, and prd: + +**For organization-wide environments:** +1. Click the **+** button next to "Organization environments" +2. Enter an environment name (e.g., "qa", "preview", "eu-prd") +3. Click **Create** +4. The environment appears in all projects immediately + +**For project-specific environments:** +1. Click on your project +2. Click the **+** button next to "Project environments" +3. Enter an environment name +4. Click **Create** +5. The environment appears only in this project + + + An environment **slug** is automatically created for SDK usage. For example, + "EU Production" becomes "eu-production" as the slug. The default environments + use "dev", "stg", and "prd" as their slugs. + + + + +API keys are generated per project + environment: + +1. Click on your project +2. Find the environment you want to use +3. Click **Generate API key** +4. Copy the key immediately (it won't be shown again) +5. Use it in your application as `TRACELOOP_API_KEY` + +See [Managing API Keys](/settings/managing-api-keys) for detailed instructions. + + + +## Viewing Your Data + +### Switching Between Projects + +The Traceloop dashboard shows **one project at a time**. To switch projects: + +1. Click the project dropdown from the main menu on the left-hand side of the dashboard +2. Select the project you want to view +3. All traces, datasets, and other data will update to show only that project + + + You cannot view multiple projects simultaneously. This is by design to maintain + clear data isolation and prevent confusion. + + +### Filtering by Environment + +Within a project, you can filter data by environment: + +1. Select your project from the dropdown +2. Use the environment filter to show only specific environments +3. This filters traces, monitors, and other real-time data by environment + +## Managing Projects and Environments + +### Renaming + +**Projects**: Can be renamed at any time +- Click on the project → Settings → Rename + +**Environments**: Cannot be renamed +- Delete and recreate if needed (see warnings below) + +### Deleting Projects + + + **Deleting a project is permanent and irreversible.** + + When you delete a project: + - All traces and spans are permanently deleted + - All datasets and their versions are lost + - All prompts, evaluators, and experiments are removed + - All API keys for that project are revoked + + **There is no way to recover this data.** + + +To delete a project: +1. Open the app settings +2. Find the project you want to delete +3. Click the 3-dot menu +4. Click **Delete project** +5. Confirm the deletion + +### Deleting Environments + + + **Deleting an environment is permanent and irreversible.** + + When you delete an environment: + - All traces for that environment are permanently deleted + - The API key is revoked immediately + - Applications using that key will stop sending data + + **There is no way to recover this data.** + + + To delete an environment: +1. Open the app settings +2. Find the environment you want to delete +3. Click the 3-dot menu +4. Click **Delete environment** +5. Confirm the deletion + + +**Organization-level environments:** +- Cannot delete the three default environments (dev, stg, prd) +- Can delete custom organization-level environments +- Deleting removes the environment from all projects + +**Project-specific environments:** +- Can delete any project-specific environment +- Only affects that specific project + +### Limitations and Permissions + +**Current limitations:** +- ❌ Cannot move or copy data between projects +- ❌ Cannot merge projects +- ❌ Cannot transfer datasets or prompts between projects +- ❌ No per-project access control (everyone in the organization can see all projects) + +**What you can do:** +- ✅ Create unlimited projects and environments +- ✅ Rename projects (but not environments) +- ✅ Everyone in your organization can manage all projects and API keys + +## Best Practices + +### Project Organization + + + + Create one project per application or major service. + + **Example:** + - "web-app" (frontend) + - "api-gateway" (backend) + - "auth-service" (microservice) + + + + Create projects based on team ownership. + + **Example:** + - "checkout-team" + - "recommendations-team" + - "infrastructure-team" + + + + Separate different products or customer segments. + + **Example:** + - "consumer-app" + - "enterprise-app" + - "internal-tools" + + + + For complex deployments with regional separation. + + **Example:** + - "app-us-production" + - "app-eu-production" + - "app-asia-production" + + + +### Environment Strategy + +**Use built-in environments for standard workflows:** +``` +dev → Local development and unit testing +stg → Integration testing and QA +prd → Live customer traffic +``` + +**Add custom environments for special cases:** +``` +qa → Dedicated QA team testing +preview → Preview deployments for each PR +canary → Canary deployments before full rollout +eu-prd → Regional production environments +``` + +### Naming Conventions + +**Projects:** +- Use descriptive, lowercase names with hyphens +- Include the service or application name +- Examples: `payment-api`, `mobile-app`, `ml-inference` + +**Environments:** +- Keep names short and clear +- Use standard terms when possible +- Examples: `dev`, `stg`, `prd`, `qa`, `preview` + +## Common Scenarios + +### Microservices Architecture + +Create one project per microservice: + +``` +Projects: +├── api-gateway (dev, stg, prd environments) +├── auth-service (dev, stg, prd environments) +├── payment-service (dev, stg, prd environments) +└── notification-service (dev, stg, prd environments) +``` + +Each service has its own API keys per environment, keeping traces completely isolated. + +### Monorepo with Multiple Apps + +Create projects per deployable application: + +``` +Projects: +├── web-frontend (dev, stg, prd) +├── mobile-backend (dev, stg, prd) +└── admin-dashboard (dev, stg, prd) +``` + +### Multi-Region Deployment + +Option 1: Use custom environments per region within one project: + +``` +Project: global-app +Environments: +├── dev +├── stg +├── us-prd +├── eu-prd +└── apac-prd +``` + +Option 2: Use separate projects per region: + +``` +Projects: +├── app-us (dev, stg, prd) +├── app-eu (dev, stg, prd) +└── app-apac (dev, stg, prd) +``` + +## Troubleshooting + +### Can't See My Project in Dashboard + +**Problem:** Created a project but it doesn't appear in the dropdown. + +**Solutions:** +- Refresh the page +- Check if you're logged into the correct organization +- Verify the project wasn't deleted + +### Data Appearing in Wrong Project + +**Problem:** Traces showing up in unexpected project. + +**Solutions:** +- Verify which API key you're using: `echo $TRACELOOP_API_KEY` +- Check which project + environment the API key belongs to +- Ensure you haven't accidentally used the wrong key in your configuration + +### Need to Move Data Between Projects + +**Problem:** Want to transfer datasets or traces to a different project. + +**Solution:** +- Data cannot be moved between projects (this is a security/isolation feature) +- For datasets: Export as CSV and import into the new project +- For traces: Cannot be transferred (must regenerate in new project) + +### Accidentally Deleted Environment + +**Problem:** Deleted an environment and lost data. + +**Solution:** +- Unfortunately, there is no way to recover deleted data +- Prevention: Always confirm before deleting +- Best practice: Back up critical datasets regularly + +## Related Resources + + + + Learn how to generate and manage API keys for your projects + + + + Set up your first project and start sending traces + + + + Create datasets within your projects for experiments + + + + Manage prompts within projects and deploy to environments + +