Projects, workflows, and environments
Organize telemetry so access, credentials, search, and production comparisons remain predictable.
Projects, workflows, and environments describe different boundaries:
| Concept | What it separates | Example |
|---|---|---|
| Project | Telemetry, access, keys, and project configuration | Customer-support agents |
| Workflow | One stable application behavior within a project | Refund assistant |
| Environment | Where that behavior ran (a tag) | production |
| Release | Which deployed version produced the run (a tag) | release-2026.08.20.1 |
Using one field for several jobs makes traces difficult to route and compare.
Design the project boundary first
A project is the main telemetry and configuration boundary. It owns or scopes traces, detections, alerts, Evals, managed prompts, API keys, PII redaction policy, AI provider keys, trace imports, and other project settings.
Create separate projects when any of these must differ:
- member access;
- telemetry credentials;
- privacy or retention policy;
- operational ownership;
- customer or regulatory isolation;
- integration configuration.
Do not create a project merely to represent every workflow or release. That fragments related evidence and makes cross-workflow investigation harder.
Create or switch projects
Projects live in the workspace switcher in the sidebar. Select a project there to switch; the dashboard and project settings follow the selected project.
To create one, open the switcher, select Add project (the plus button next to Project), enter a Project Name and optional Description, and select Create Project. Organization owners, admins, and members can create projects; guests cannot. Only organization owners and admins can archive or delete a project, so other members should ask one of them.
Keep project names unique within the organization. Browser write keys choose their destination by project name, and an ambiguous name is rejected.
Example workspace design
Organization: Acme
├── Project: Customer support
│ ├── Workflow: refund-assistant
│ ├── Workflow: order-status
│ └── Workflow: escalation-router
└── Project: Internal research
├── Workflow: market-research
└── Workflow: account-briefingThis split is useful when support and internal research have different users, keys, and data policies.
Use stable workflow names
A workflow identifies an application behavior people will search and compare over time. The SDK sets it with workflow_name (or a named workflow root), and the trace list can filter by Workflow.
Good names describe the feature:
- refund-assistant
- checkout-agent
- support-ticket-triage
- policy-research
Avoid values that change per run:
- customer IDs;
- request IDs;
- timestamps;
- model versions;
- environments;
- release numbers.
Those values belong in tags, sessions, end-user identity, or attributes.
A single process can emit several workflows when it serves several business behaviors. Each explicit root should carry the intended workflow identity. See Workflow name and Multiple workflows.
Keep environments and releases separate
Environment and release identify where and which version ran. Neatlogs does not have dedicated environment or release fields: record them as tags on init(), and filter the trace list by Tags.
Use stable values such as:
- production
- staging
- release-2026.08.20.1
- prompt-refund-v14
This lets you answer:
- Did the regression start after one release?
- Does staging reproduce production behavior?
- Which prompt version produced the failed run?
- Are quality trends mixing unrelated environments?
Do not encode the environment or release into the workflow name. refund-assistant-production-v14 will create a new workflow series every time the version changes.
Understand project keys
A telemetry credential sends data to a fixed project, or to the project it names. The dashboard project currently open in a user's browser does not change that destination.
| Credential | Where you get it | What it can do | Use it for |
|---|---|---|---|
| Project API key | Settings → Project → API keys, Project API key section | Ingest and read for one project | Server-side SDKs (NEATLOGS_API_KEY) and SDK features that read project data, such as managed prompts |
HTTP ingest key (nlw_) | Same page, HTTP ingest key section | Ingest only, through POST /v1/trace; personal to you and usable for any project in the organization, named by project | Browser and other public client code. See Browser SDK. |
Project ingest credential (nli_) | Public API or CLI | Ingest only, bound to one project, expiring, and rotatable | Server-side export when you need a credential you can rotate or revoke |
| Service-account token | Settings → Organization → Service accounts | Public API calls on the projects the account is bound to, limited by its scopes | CI, scripts, and agents using the Public API or CLI |
Browser code must only ever use an nlw_ HTTP ingest key. A project API key also grants read access, so never embed it in client-side code.
The project API key can be revealed and copied, but the dashboard does not rotate or revoke it. Store it in the approved secret manager and label its deployment purpose. When you need rotation, use an expiring project ingest credential for export instead. Rotating or revoking your HTTP ingest key (Rotate key or Revoke key) stops the old key immediately in every project that uses it.
Service accounts are created and managed by organization owners and admins. Other members can ask one of them to create an identity and bind it to the right projects.
When traces appear in the wrong project, check the key used by the application, the project name sent with a write key, or the import mapping before changing dashboard filters.
Organize native and imported traces
An import maps one source project into a target Neatlogs project. Configure it under Settings → Project → Trace imports; see Import traces.
Native and imported evidence can be searched and analyzed together when their workflow, environment, and field semantics are comparable. The source may omit parent relationships, tool results, or attributes that native instrumentation captures.
Keep source identity visible during migration or overlap. Avoid counting the same application execution twice when both an import and native instrumentation include it.
Review the design before production
Check:
- each project has a clear access and data boundary;
- each application behavior has a stable workflow name;
- environments and releases use consistent tags;
- each deployment uses the credential intended for its project;
- imported and native naming is comparable;
- dashboards and Evals can filter production from test traffic.
Changing inconsistent names early is easier than repairing months of fragmented telemetry.
Frequently asked questions
Should development and production share a project?
Separate them when access, privacy, or operational ownership differs. If they share, tag the environment consistently and include that tag in every production filter.
Can one application use several projects?
Yes. Use separate project keys or isolated clients and choose the boundary intentionally. See Secondary clients.
Can a project contain several workflows?
Yes. That is the normal model for related application features with shared ownership.
Does changing the dashboard project move telemetry?
No. The ingestion key, the project named by a write key, or the import mapping determines the destination.
What if a workflow is renamed?
Treat the new name as a new comparison identity. If the behavior did not actually change, keep the stable name and represent the release in a tag.
What if the project API key leaks?
The dashboard cannot rotate or revoke it. A credential migration can move export to a project ingest credential and then revoke the old project key. Before revoking it, account for SDK features that read with the project key, such as managed prompts. Contact support if you need help.