> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Help

> Prepare a BYOC service-adapter support case with safe request evidence and clear vendor/customer responsibilities.

Start a support case with the observed impact, affected application and customer deployment. You do not need to prove whether the application, adapter or native target service caused the issue. Use your agreed channel, or [contact Tensor9](https://www.tensor9.com/contact/).

The hosting customer may hold evidence that the vendor cannot access directly. Keep those access boundaries intact and identify the missing observations in the case. Do not delay an incident report while waiting for every field below.

## Prepare the incident handoff

<Steps>
  <Step title="Identify the application and customer deployment">
    Record the app name, customer name, release, appliance form factor, adapter version and time window with a timezone. Describe which operation fails and the business impact.

    For example: `orders-api` on the `example-customer` Azure appliance has slow conditional `UpdateItem` requests against the `orders` table; reads still succeed. Include the exact deployed release rather than assuming it matches the vendor's current development branch.
  </Step>

  <Step title="Preserve the original response and effect evidence">
    Capture status, error code, origin request identifiers and any target identifiers or Explain receipt. Preserve the result before a retry changes the evidence.

    A timeout does not establish that a write failed. Ask an authorized operator to inspect the exact target resource when a state read can resolve the uncertainty. Do not replay a customer write merely to obtain a report.
  </Step>

  <Step title="Inspect the directed profile locally">
    For an S3 request adapted to Google Cloud Storage, use:

    ```sh theme={null}
    tensor9 explain \
      -origin aws::1.0.0::s3 \
      -target google::1.0.0::gcs \
      -operation PutObject \
      -fmt Human
    ```

    This reads the published service profile without starting an adapter or calling a cloud API. It does not require access to the customer's appliance. It also does not prove which adapter version or mapping served the incident request; retain the deployment context separately.

    Use the [BYOC service catalog](/byoc/service-adapters/catalog) to select the actual origin and target pair, and [Using tensor9 explain](/cloud-adapter/debugging/using-explain) for the shared CLI reference.
  </Step>

  <Step title="Read captured explanations through the authorized owner">
    If the original response includes `x-t9-explain-id`, have the authenticated request owner retrieve that report. Record its revision, assurance, observations and unknowns. A receipt does not establish successful execution, complete capture or persisted report availability.

    The report owner can share an authorized, sanitized export with the vendor and Tensor9. Preserve it before acknowledging the exact consumable revision. Do not transfer credentials or assume a copied report grants access to the appliance. Follow [Debugging Service Adapters](/byoc/service-adapters/debugging/overview).
  </Step>

  <Step title="Reproduce in a matching test appliance when needed">
    Keep the same form factor, service mapping and relevant release/configuration. Use synthetic data and a disposable resource. Swapping Cosmos DB for a different backend changes the investigation rather than resolving it.

    Where supported, an explicit signed control requests a non-executing explanation:

    ```text theme={null}
    x-t9-explain: {"version":1,"mode":"Explain","fmt":"Json"}
    ```

    Add it before signing and use an explanation-aware request path. Executing a test with `ExecuteAndExplain` requires the same approval and cleanup as an ordinary service operation. See the [shared header reference](/cloud-adapter/debugging/response-headers).
  </Step>

  <Step title="Combine vendor and customer evidence">
    The vendor supplies application behavior, request context and release changes. The customer supplies permitted native resource observations, provider metrics, capacity settings and relevant permission or quota changes.

    Send a small sanitized bundle through the agreed support channel. State what was observed, what remains unknown and which live actions have already been taken. Agree who will authorize the next test.
  </Step>
</Steps>

<Warning>
  `x-t9-explain: true` executes the request and records an explanation. It is not a preview. Missing Explain or request-effect headers do not prove that nothing was written. An investigation must not silently replay mutations inside a customer environment.
</Warning>

## Evidence checklist

| Evidence                                                  | Typical source                             | Why it matters                                         |
| --------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------ |
| App, customer, release and appliance form factor          | Vendor release records                     | Identifies the deployed version and customer path.     |
| Origin operation and exact target mapping                 | Vendor configuration and service reference | Distinguishes different directed adapters.             |
| Timestamp, error and request identifiers                  | Application response                       | Correlates the original attempt without replay.        |
| Explain mode, report ID, revision and limitations         | Authenticated report owner                 | Shows what the adapter actually recorded.              |
| Target state and native request identifiers               | Authorized customer or vendor operator     | Helps establish whether the operation took effect.     |
| Native capacity, throttling and health observations       | Customer's cloud monitoring                | Separates resource pressure from adapter behavior.     |
| Tuning tags and configuration revision                    | Vendor release and resource records        | Establishes which settings were requested and applied. |
| Workload sizes, operation mix, rates and key distribution | Application monitoring                     | Makes performance observations interpretable.          |
| Recent changes and actions already taken                  | Vendor and customer incident timeline      | Avoids repeated tests and mistaken attribution.        |

Do not send credentials, signed URLs, customer payloads or unrestricted logs. Explanation reports and resource names can contain customer information; share only what the customer's handling rules permit.

## Example: conditional writes on Cosmos DB

For the `orders-api` example, the vendor captures one slow conditional `UpdateItem`, its request identifiers, item size and condition shape. The customer captures the same interval's Cosmos DB throttling, RU consumption and partition observations. An authorized owner exports the request explanation if available.

Those pieces answer different questions. The profile describes supported behavior; the report describes recorded adapter decisions; the target observation helps establish what was committed. A throttled native call is evidence of a target response, not proof that the adapter's request construction and retry behavior were correct.

Tensor9 can help compare the evidence before recommending a tuning change or a smaller test. Check [How Support Works](/byoc/support/overview) for responsibilities and [DynamoDB to Cosmos DB](/byoc/support/service-adapter-slas#dynamodb-cosmosdb) for the pair-specific scope.

## Performance reports need a time window

Provide arrival rate, completed-operation rate, errors and latency percentiles over the same interval. Include batch sizes, item or object sizes and whether the issue coincided with a burst, rollout or resource failure. A single successful request does not demonstrate production capacity, and an isolated slow request is not a monthly SLA calculation.

Distinguish native target work from adapter work before, between and after target calls. See [Service Levels](/byoc/support/service-levels), [Scaling and Limits](/byoc/support/scaling-and-limits) and the [service-adapter SLA tables](/byoc/support/service-adapter-slas).

## Live access remains an explicit decision

Opening a support case does not grant Tensor9, a vendor operator or a coding agent unrestricted customer access. Use the existing [operations security](/byoc/fundamentals/operations/security) and [break-glass](/byoc/fundamentals/break-glass) workflows when an investigation needs live commands or changes. State the exact intended action and its possible effects before requesting approval.