Skip to main content
Before running a tensor9 command, install the CLI, set T9_API_KEY, and verify your customer account. Online commands are authenticated and their adapter detail is limited to mappings your account is entitled to use.
Explain answers three different questions about a service adapter:
  1. What does this origin-to-target profile support? Authenticate to Tensor9 and inspect the entitled directed service profile without starting an adapter or contacting an origin or target cloud provider.
  2. What would this request do? Run the adapter in Explain mode. The requested service action is not performed.
  3. What did this request attempt and observe? Run the request in ExecuteAndExplain mode. The action has its ordinary effects and the adapter records an explanation.
Those questions are related, but their evidence is not interchangeable. A profile can establish documented coverage; it cannot prove what a deployed process did. A preview can expose a selected mapping and blocking constraint; it cannot prove that a provider allocation would succeed. An executed explanation can record an attempted target call and observed response; it cannot establish facts outside its stated capture scope.
Request-report retrieval requires an adapter version that publishes its dedicated t9 endpoint and signing region. Developer CLI retrieval additionally requires -report in the installed command’s help. Check installed support before following those examples; this guide does not establish availability in older deployments. Profile inspection has its own account entitlement and version requirements.

​
Choose the right form

x-t9-explain: true selects ExecuteAndExplain in Human format. It is not a dry run. Use the explicit version-1 configuration when you need Explain mode.

​
Discover and inspect a directed service profile

The public catalog provides exact origin identifiers, backend choices and documented compatibility. To inspect an account-entitled profile through the CLI, discover the exact target identifiers your account can run for that origin:
This authenticated result is bounded to the supplied origin and your account’s entitlements. It does not enumerate other origins or export the adapter corpus. The profile form uses that exact origin identifier and one returned target identifier. It contacts Tensor9 to authorize the request and retrieve bounded detail for an entitled direction. It does not start an adapter or contact the origin or target provider.
Use -operation to focus the rendering on one or more comma-separated origin operations. Use Human for reading, Agent for compact evidence with stable references, or Json for versioned structured output. The command above answers questions such as:
  • Is PutObject represented by the selected S3-to-GCS profile?
  • Which behavioral differences and constraints are documented for that direction?
  • Which configuration and tuning choices affect the mapping?
  • Which parts of the behavior remain target-specific?
Read the result beside the S3 service catalog entry. The public catalog already supplies operation-level compatibility and service-level terms; the authenticated CLI renders the account-entitled profile for a focused query. Coverage is directed: an S3-to-GCS profile does not imply the reverse direction or another target has identical behavior. The following command inspects a different profile and illustrates a profile facet:
The ::table facet identifies the profile being inspected. It is not necessarily the runtime service name used by a request endpoint. The DynamoDB catalog entry publicly documents its operations and qualifications; the CLI narrows inspection to an entitled direction.

​
Retrieve an existing explanation

When you already have an x-t9-explain-id receipt, use the signed SDK retrieval flow with the same owner’s IAM credentials. Call T9CloudAdapter.GetExplanation through the dedicated t9 endpoint, signed as t9 with its published signing region. Select fmt as Human, Agent or Json. Decode the outer AWS JSON response’s body string to read the selected rendering; for Json, parse that string as JSON. This read neither launches an adapter, executes the original operation nor acknowledges the report, and it needs no Tensor9 API key. A new assumed-role session cannot read another session’s report. An optional positive minimumVersion selects a known revision or newer; omit it for a first read. tensor9 explain remains profile inspection only.

​
Preview a particular request

Explain mode evaluates a request through the synthetic origin service without performing the requested service action. A completed preview returns an origin-protocol 409 ExplainedNotPerformed error carrying a report ID. Call T9CloudAdapter.GetExplanation through the dedicated synthetic AWS t9 endpoint to read the selected mapping, effective configuration, authorization decision, state observations and constraints. Both clients use normal IAM credentials and SigV4. The application client signs for its native AWS service; report calls sign as t9 using the configured report endpoint and region. A useful preview records its evidence basis:
  • Observed facts came from an identified source or versioned snapshot.
  • Derived facts follow from other named facts or rules.
  • Hypothetical facts describe what would be selected if execution continued.
  • Unknown or unsupported facts are retained as limits instead of being silently interpreted.
That distinction matters. A hypothetical S3-to-GCS mapping says which target operation the adapter selected; it does not say that bytes were uploaded. A derived configuration choice says which supported target setting would be selected; it does not prove that the provider applied it or measure the resulting performance or cost. Use preview when you need to:
  • understand why an input or dependency would be refused;
  • compare the default configuration with a supported tuning choice;
  • identify the target resource and field mapping before execution;
  • narrow a permissions or compatibility question without replaying a mutation.
See Using tensor9 explain for profile inspection and Explaining SDK Requests for a signed per-request control.

​
Execute and explain a real request

ExecuteAndExplain performs the origin operation with its ordinary effects and records what the adapter attempted and observed. Treat it as a production-capable mutation, not an inspection-only switch. For an existing SDK request, the explicit control is:
The header must be present before request signing. The native response can include x-t9-explain-id, x-t9-explain-mode and x-t9-explain-expires-at. Preserve the service result and supply the ID to GetExplanation on t9. The receipt does not prove that asynchronous work finished or every intended target effect occurred. Reports expire 24 hours from creation by default; reads do not extend that deadline. Before using ExecuteAndExplain:
  • choose an isolated resource or an operation whose effects you intend to perform;
  • decide who owns report retrieval and acknowledgment;
  • preserve the native response, report receipt, request identifiers and target state;
  • plan cleanup based on observed resource state, not on the presence of a receipt;
  • avoid automatic retries until the operation’s idempotency and current target state are known.

​
Read one decision, not just the conclusion

An explanation connects events to facts. For example, an illustrative VPC report records a decision event:
The referenced fact states that a no-live-instance-dependency constraint was violated and names the observed instance fact that supports it. That chain answers why the operation was rejected. It also preserves important limits:
  • the authorization fact in that report is Allow; authorization was not the rejecting decision;
  • the target VNet mapping is hypothetical, not an observed deletion;
  • the dependency observation names a snapshot and read version;
  • the report says its timeline is capture order, not a cross-service clock.
Follow evidence references rather than inferring causality from adjacent lines. Reading an Explanation walks through the same fixture in Human, Agent and JSON formats.

​
Turn evidence into a bounded next action

An explanation is useful when it changes the next diagnostic step: Explanation detail is also not the same as service support. A report can accurately describe a refusal or a known limitation. Use the service catalog for the supported behavior, then use the report to understand the selected path for one profile or request.

​
Continue the investigation