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. Attempt to retrieve the report named by the receipt, preserve an authorized and redacted copy when available, and only then have the report owner 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 canonical Explain request and response reference defines the control syntax, receipt headers, report retrieval and acknowledgment statuses. BYOC uses that same service-adapter protocol at the application’s existing adapter endpoint; it does not require installing a separate Cloud Adapter product.

​
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.

​
Read the explanation before guessing

Read the report in the format appropriate to the investigator: Human for an operator, Agent for a bounded coding-agent investigation, or JSON for tooling. Follow Reading an Explanation to distinguish observed facts, adapter decisions, constraints, target mappings and unknowns. 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 read and acknowledge through the report HTTP routes; 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.