> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/cisco-nso/trace-id-propagation/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Trace-ID propagation

> How the NSO adapter generates and propagates trace-ids across JSON-RPC, RESTCONF, and NETCONF, and where to find them for troubleshooting.

ISM 6.5.1+

Cisco NSO assigns a trace-id to every transaction it processes. The NSO adapter generates a trace-id for each transaction it sends to NSO and returns it in the task response, letting you trace a request end-to-end — from an Itential Platform workflow step, through the adapter, into NSO's own logs, and back into the stored task result.

This gives you a single ID to search on when correlating an Itential Platform workflow run with its corresponding NSO transaction, rather than matching timestamps across two separate logging systems.

This feature is enabled by default and requires no configuration. It applies automatically once you're on a supported adapter version.

## Version requirements

| Requirement              | Value                 |
| ------------------------ | --------------------- |
| Minimum adapter version  | NSO adapter ISM 6.5.1 |
| Tested NSO version range | 5.7 through 6.7       |

## How trace-id generation works

Cisco NSO changed how it exposes trace correlation starting in NSO 6.7: earlier versions use NSO's own `trace-id` extension, while 6.7 and later use the W3C Trace Context standard (`traceparent`). The adapter detects the connected NSO version automatically and uses the matching mechanism for each protocol — you don't need to choose or configure anything.

| Protocol | NSO earlier than 6.7                                                        | NSO 6.7 and later                                                        |
| -------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| JSON-RPC | `trace-id` flag on the `commit` and `validate_commit` calls                 | `traceparent` HTTP header on every `POST /jsonrpc` call                  |
| RESTCONF | `trace-id` query parameter (`?trace-id=...`)                                | `traceparent` HTTP header on outgoing requests                           |
| NETCONF  | `<trace-id>` child element, only on `edit-config` and `prepare-transaction` | `traceparent` namespace-qualified XML attribute on every `<rpc>` element |

Protocol-specific notes:

* **RESTCONF** is standard HTTP, so older NSO versions safely ignore the `traceparent` header if they don't recognize it — this doesn't affect compatibility with earlier NSO releases.
* **NETCONF** on NSO 6.7 and later looks like this:

  ```xml
  <rpc xmlns:w3ctc="urn:ietf:params:xml:ns:netconf:w3ctc:1.0"
       w3ctc:traceparent="00-<trace-id>-<parent-id>-01">
  ```

## Where to find the trace-id

* **In the task response**: The adapter returns the trace-id as a `traceId` field on the task's result object, so it's visible directly in the workflow's task output:

  ```json
  {
    "success": true,
    "result": {
      "action": "update",
      "...": "...",
      "traceId": "4b7a1e3c9d2f4a6b8e5c1a0d3f9b2e7c"
    }
  }
  ```

* **In NSO's own logs**: Every log line NSO emits while processing a request includes the same trace-id the adapter sent, so you can search for it in `devel.log`, `netconf.log`, or `audit.log`.

* **Persisted with the task result**: The trace-id is stored in MongoDB alongside the task's success or error data, so it remains available for troubleshooting after the fact.

A trace-id is only included for transactional adapter methods — provisioning, service configuration, dry runs, template application, and raw NETCONF RPC calls. Simple read or query calls don't return a trace-id, since they don't correspond to an NSO transaction.

> How the NSO adapter generates and propagates trace-ids across JSON-RPC, RESTCONF, and NETCONF, and where to find them for troubleshooting.