Skip to main content
Service adapters run inside the customer appliance, but you can investigate their decisions without treating them as a black box. Start with Explain: it can describe the selected service mapping and, for covered operations, produce a report about how an origin request was interpreted and mapped to the target. For an adapter issue in Tensor9 BYOC, record the application version, test or customer appliance, target cloud, origin service and operation. The same origin request may reach different backends in different deployments, so identify the actual mapping before comparing results.

​
Choose the safest Explain workflow

Use the least invasive workflow that answers the question:
  1. Inspect the directed service profile with tensor9 explain. This reads the published origin-to-target mapping and does not launch an adapter or call a cloud API.
  2. Reproduce the request in an approved test appliance. Use Explain mode when you need a hypothetical decision without applying the target operation. Use ExecuteAndExplain only when the test is meant to perform the operation.
  3. Add the x-t9-explain request control through the application’s existing, signed SDK request. The adapter returns an explanation receipt when the selected operation supports request explanation.
  4. Retrieve the report through the install’s dedicated synthetic AWS t9 service using the original request owner’s IAM identity. Preserve an authorized and redacted copy when available, then acknowledge the exact consumable revision.
x-t9-explain: true means ExecuteAndExplain. The request can change the target environment. It is not a preview switch. Use the explicit Explain mode for a hypothetical request, and never replay an uncertain write merely to obtain a report.
The application sends its operation through the existing native service client, signed for that service, such as s3 or dynamodb. Its response stays in the native protocol and carries an explanation receipt when available. Explanation content is retrieved separately from the synthetic AWS t9 service, with SigV4 signing service t9. BYOC includes this protocol without a separate Cloud Adapter installation.

​
Establish the deployment context

Before interpreting a report, identify the deployment it came from. For a vendor investigation, record:
  • app, customer and release, such as orders-api, example-customer and example-release;
  • appliance form factor, origin service, target service and selected mapping;
  • application, service-adapter and CLI versions;
  • operation, timestamp and origin-facing endpoint;
  • response status, origin request IDs and target request IDs, when supplied;
  • explanation report ID, mode and revision;
  • relevant tuning tags and sanitized adapter configuration; and
  • the target resource observations that establish whether a mutation occurred.
Do not infer this context from a report copied from another deployment. A copied report can be useful evidence, but it does not grant access to its source appliance and does not prove that another release selected the same mapping.

​
Capture one request

Record its timestamp, endpoint, status, error code and response headers. Preserve the exact request identifiers returned by the adapter. Redact credentials, signed URLs, session tokens and sensitive payloads before sharing a reproduction or logs. Do not enable unrestricted SDK wire logging in a customer environment merely to collect identifiers. Wire logs can contain authentication material and application data. Use scoped collection and the customer’s approved access and handling procedures. When request explanation is enabled, capture the explanation receipt alongside the ordinary SDK result. A receipt is a correlation locator and records capture intent; it does not prove that a report row was persisted, that the operation succeeded, that the report is complete, or that the request was authorized. Keep the origin response, target observation and explanation report as separate evidence.

​
Configure the report client

The following workflow requires an install version that publishes the dedicated report endpoint and signing region. If those settings are absent, confirm the appliance version and its supported report workflow with the vendor; do not infer an endpoint from another service URL. Use a separate client for the synthetic AWS t9 service. In a BYOC workload, read T9_ENDPOINT_URL and T9_SIGNING_REGION supplied by the deployment for the same install as the original request; see Service-adapter report endpoints. A receipt identifies a report, not its endpoint or an access credential. Use the same credential provider as the original workload when it still resolves to the same authenticated owner. A new assumed-role session does not acquire another session’s reports. A Tensor9 API key, control-plane login or target-cloud credential does not authorize this request. See AWS IAM credentials for appliance-issued credentials and session tokens.

​
Retrieve an existing report

Use the signed T9CloudAdapter.GetExplanation request described in Read the explanation before guessing, with the receipt’s report ID and the published t9 connection settings for the original install. Sign as service t9 using its configured region and the original request owner’s IAM credentials, including the original session token when temporary credentials were used. This read neither launches an adapter, executes the original operation nor acknowledges the report, and it needs no Tensor9 API key. Decode the outer AWS JSON response’s body string to read the rendering. tensor9 explain inspects a directed service profile only; it does not retrieve a deployed request report.

​
PostgreSQL-backed service adapters

PostgreSQL plan capture is under development for supported statements. BYOC uses the same owner-authenticated t9 report workflow. A PostgreSQL backend alone does not establish plan support for an operation or installed release. For a supported workload statement, the adapter plans the original compiled SQL and encoded parameters on a separate authenticated, read-only PostgreSQL connection using EXPLAIN (FORMAT JSON), without ANALYZE. Planning does not execute the write again or replace the native service result. Its planningContext is committed-state-observation: an estimate of separately observed committed state, not the original transaction snapshot or measured execution time. Human and Agent text renderings retain the complete plan JSON, as does the JSON report. That full plan is private to the exact report owner and original IAM session. Relation and index names, predicates and application literals can occur inside it; review an exported copy before sharing. A plan can arrive in a later report revision. Read the same report with bounded backoff instead of replaying the operation; its retention deadline stays fixed. Each active planning profile needs a separate allocation for a pool with a maximum of one connection, counted for each configured replica in addition to native connections. Another service’s allocation does not cover it. Account for the database’s other consumers and connection limits before treating the allowance as available capacity. Unavailable planning capacity or context affects the diagnostic evidence, rather than changing the ordinary operation’s outcome. Use the native result and independent resource observations to assess effects; a plan alone does not prove a commit.

​
Read the explanation before guessing

Retrieve the report separately and record its expiry before sharing evidence. The default lifetime is 24 hours from creation; reads do not renew it. Use the receipt’s x-t9-explain-expires-at or the JSON report’s reportExpiresAt. Read in the format appropriate to the investigator: Human for an operator, Agent for a bounded coding-agent investigation, or JSON for tooling. Distinguish observed facts, adapter decisions, constraints, target mappings and unknowns when interpreting the report. Call T9CloudAdapter.GetExplanation using the report ID from x-t9-explain-id. Include Content-Type: application/x-amz-json-1.1 and X-Amz-Target: T9CloudAdapter.GetExplanation before signing; the target header must be covered by the signature. For example, the JSON request body is:
The HTTP 200 response is an AWS JSON object containing reportId, revision, fmt and body. The body field is a string containing the selected rendering. For fmt: "Json", parse that string as JSON to read the report. Human and Agent select text renderings. An optional positive minimumVersion requests a report at or beyond a known revision; it does not rerun the original operation. When the response includes acknowledgeRevision, preserve the report before calling T9CloudAdapter.AcknowledgeExplanation on the same endpoint. Sign its target header and use this JSON body, replacing the example revision with the advertised value:
Report responses use Cache-Control: no-store. Failures use AWS JSON __type and message fields; report disposition and revision appear only when they can be disclosed to that caller. Poll report availability with bounded reads; do not repeat the application request to obtain another report. An explanation can establish which mapping was selected and why an adapter accepted, refused or translated a covered request. It cannot establish facts that were not captured. In particular:
  • an allowed authorization fact does not prove the target accepted the request;
  • a target mapping does not prove a write committed;
  • a partial report does not prove the remaining steps did not occur; and
  • the absence of an explanation receipt does not prove the request had no effect.
Compare the report’s causal sequence with the origin response and the native target state. If they disagree, preserve all three before running another test.

​
Read the diagnostic headers

Request identifiers are not proof that a backend operation completed or that a retry is safe. The request-effect header is not emitted by every adapter or every failure path. An absent or unrecognized request-effect value means the effect is unknown. Check resource state and the operation’s idempotency rules before retrying a write. A timeout can occur after the backend performed the operation. Python clients using Botocore response dictionaries expose headers in ResponseMetadata.HTTPHeaders. A caught ClientError has its response dictionary on error.response; a transport exception may have no HTTP response. Collect only the metadata needed for the investigation.

​
Trace the deployment-specific path

Check the origin client endpoint, adapter configuration, backend identity and the resource state in the customer’s target environment. Distinguish origin authorization from backend permissions. An application’s ordinary network traffic or native database protocol may follow a different path from its cloud-management API calls. Use response identifiers to find the corresponding adapter logs in your approved observability workflow. Preserve relevant tuning tags, including tags set during resource creation. An empty test resource can hide a state-dependent bug. Use the Adapter Errors provenance header when it is present to choose the next system to inspect. Error provenance and Explain answer different questions: provenance identifies the layer that returned a failure, while Explain describes the adapter’s reasoning and recorded request path. Neither is a substitute for checking target state after an uncertain mutation.

​
Reproduce in a test appliance

Prefer a test appliance with the same form factor and a minimal workload. Use synthetic data and scoped credentials. Reproduce the setup that matters to the request, then compare the observed result with the service’s operation coverage and documented differences. Do not replay a mutating request in a customer appliance merely to get a cleaner error. Determine whether the original request already changed resources and obtain appropriate authorization before any further live action. For a useful reproduction, keep the deployment shape faithful while reducing the data and permissions:
  1. Match the customer appliance form factor, release and service mapping.
  2. Create a disposable resource with synthetic data and a scoped origin identity.
  3. Inspect the static profile for the exact origin, target and operation.
  4. Run a hypothetical explanation first when the operation supports it.
  5. If execution is necessary, use a unique resource name or idempotency key and observe the target before and after the request.
  6. Retrieve and redact the report before acknowledging it.
  7. Remove only the resources created by the test and record the cleanup result.
Do not silently swap a different backend into the reproduction. A DynamoDB request mapped to Cosmos DB can make different decisions from the same request mapped to another target, and a successful substitute test does not resolve the customer incident. Anchor the investigation in the exact BYOC service reference. For storage examples, start with Amazon S3 or Amazon DynamoDB, then read across the selected target profile rather than assuming that another backend has the same behavior.

​
Coordinate vendor and customer responsibilities

The vendor and customer often hold different pieces of the evidence. Before sending the request, decide which application or collector will use the authenticated owner identity. That owner alone can retrieve and acknowledge through the t9 service; it exports sanitized evidence to approved participants out of band. The originating request fixes the report owner to its authenticated principal; ownership is not reassigned after the response. The owner shares redacted evidence with approved participants and acknowledges only the exact revision advertised as consumable. Retrying the same owner acknowledgment at the same sealed revision is idempotent. Do not acknowledge merely to make an investigation queue look clean.

​
Use coding agents with captured evidence

The service reference, diagnostic response headers and captured logs can help identify the selected mapping and relevant limits. Documentation cannot establish what happened in a particular live request, and an investigation must not silently replay mutations against customer resources. You can ask Codex, Claude or another coding agent to investigate a sanitized reproduction through public CLI help and documentation. Give it explicit limits, for example:
The agent does not need Tensor9 source code or a new standalone Cloud Adapter installation. Review its evidence and suggested actions under your existing BYOC operations and customer-access controls.

​
Report an unresolved issue

Use Getting Help for the step-by-step vendor/customer handoff. How Support Works separates adapter responsibilities from native target-service responsibilities; you do not need to establish fault before opening a case. Include versions, mapping, operation, timestamp, request identifiers, explanation report ID and revision, redacted error and configuration, relevant tags, reproduction steps and expected behavior. State what you verified about side effects, what remains unknown and whether the issue also occurs in a test appliance. Share the smallest useful evidence bundle, not the customer’s complete logs. A complete handoff for the orders-api example contains the example-customer appliance and example-release identity, the selected service mapping, adapter version, one sanitized origin response, native target observations, the redacted explanation report, report capture and acknowledgment state, and the exact next test. Keep credentials, signed URLs, customer payloads and unrestricted logs out of the bundle.