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

# Tuning Your Adapters

> Tune capacity, concurrency, cost and behavior for each service and backend.

> [!NOTE]
>
> Before running a `tensor9` command, [install the CLI, set `T9_API_KEY`, and verify your customer account](https://docs.tensor9.com/cloud-adapter-early-access/getting-started/install-and-authenticate). Online commands are authenticated and their adapter detail is limited to mappings your account is entitled to use.

Tuning starts with a workload and the target resources that serve it. For DynamoDB on Cosmos DB, that may mean choosing a container's throughput budget. For SQS on PostgreSQL, it may mean increasing worker concurrency, changing visibility timeouts, or sizing the database shared by several queues. Those changes belong in different places and have different effects.

> [card] [Tuning AWS DynamoDB](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-dynamodb.md)
>
> Cosmos DB capacity, Firestore updates, Spanner and Bigtable connections, and PostgreSQL sizing.

> [card] [Tuning AWS SQS](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-sqs.md)
>
> Polling, visibility, retention, FIFO workloads and target backend capacity.

> [card] [Tuning AWS S3](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-s3.md)
>
> S3-to-GCS transfer concurrency, lifecycle transitions and cost.

> [card] [Tuning AWS RDS PostgreSQL](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-rds-postgresql.md)
>
> Database capacity, connection budgets, query settings and recovery checks.

> [card] [Tuning AWS Aurora PostgreSQL](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-aurora-postgresql.md)
>
> Writer and reader capacity, connection routing and workload isolation.

> [card] [Tuning AWS ElastiCache](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-elasticache.md)
>
> Memory, eviction, client concurrency and engine-specific controls.

> [card] [Tuning AWS OpenSearch](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-opensearch.md)
>
> Index layout, ingestion, search latency and cluster resources.

> [card] [Tuning AWS Lambda](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-lambda.md)
>
> Warm capacity, execution resources, timeouts and downstream budgets.

> [card] [Tuning Examples](https://docs.tensor9.com/cloud-adapter-early-access/tuning/examples.md)
>
> Worked scenarios and a repeatable comparison worksheet.

## Choose the correct control

| Control | Example | Scope | Where to set it |
| - | - | - | - |
| Origin API setting | SQS `VisibilityTimeout` | Queue behavior | AWS create or update request |
| Target resource tuning | Cosmos DB autoscale maximum | A table-owned container | Supported `t9:tuning:` tag on the origin create request |
| Backend selection | Provisioned Cosmos DB rather than Firestore | Resource's storage implementation | `t9:backend`, where supported |
| Shared infrastructure capacity | Cloud SQL CPU, memory, storage and availability | Every table or queue using that instance | Backend provisioning configuration |
| Adapter runtime setting | PostgreSQL connection pool size | Adapter process and backend connections | Documented adapter or process setting |
| Application setting | Worker count, SDK concurrency or timeout | One client or worker fleet | Application or SDK configuration |

A queue's visibility timeout does not give its database more CPU. A larger database does not make an unsafe retry safe. Diagnose the limiting factor before choosing a control.

### Defaults and backend selection

An origin-and-target installation derives ordinary mappings from the catalog. Do not add a service declaration solely to repeat a default mapping. Supply resource-specific backend selection when the service offers alternatives, and installation details when a backend needs pre-provisioned infrastructure. SQS on Cloud SQL needs a provisioned database and an authorized connection before a queue can use it.

The explicit `--origin` and `--backend` arguments to `tensor9 adapt svc run` select a single local adapter to try. They do not mean every service must be declared in a provisioned installation. See [configuration](https://docs.tensor9.com/cloud-adapter-early-access/configuration/overview.md).

## Resource tuning tags

The tag name has this shape:

```text theme={null}
t9:tuning:<target-field-path>
```

The path identifies a field documented for that service and backend. It is not unrestricted access to the target API. Values travel in the origin API's tag format: DynamoDB uses a list of `Key` and `Value` entries; SQS and EKS use maps in their create requests.

For a DynamoDB table with its own provisioned Cosmos DB container, the capacity example is:

```json theme={null}
{
  "Key": "t9:tuning:container.properties.options.autoscaleSettings.maxThroughput",
  "Value": "40000"
}
```

This is an autoscale maximum of 40,000 request units per second for that container. It is not a table-size limit, an AWS write-capacity value, or an account-wide spending cap. The [DynamoDB guide](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-dynamodb.md) includes the surrounding request, ownership requirements and verification steps.

Use only documented paths for the chosen mapping. Do not construct a tag from an arbitrary provider field, put credentials in a tag, or use a tuning tag to change resource identity.

### Keep directives separate

| Directive | Purpose |
| - | - |
| `t9:tuning:<path>` | Supply a supported target-resource setting. |
| `t9:backend` | Select a backend; this is not a tuning field. |
| `t9:ack:unprojected` | Acknowledge named origin attributes that are not projected, where supported. |
| `t9:ack:degradation` | Acknowledge a named behavioral difference, where supported. |

Acknowledgements do not restore the behavior being acknowledged. Use only tokens documented for the exact mapping. `t9:tuning:backend` is not another spelling of `t9:backend`.

## Resource ownership matters

Suppose two DynamoDB tables share one Cosmos DB container. Raising its throughput changes the budget available to both. It cannot give one table an independent capacity guarantee. Use a table-owned container when independent capacity is a requirement.

Other backend settings have similar boundaries:

* A Spanner instance can serve several tables. Its compute capacity is an instance setting.
* A Bigtable cluster can serve several tables. Adding nodes changes cluster capacity, not a table's key distribution.
* A PostgreSQL server can serve several queues and tables. Connections, storage and CPU are shared.
* An Azure Service Bus namespace can serve several queues. Namespace capacity and queue properties are separate controls.

Keep shared infrastructure settings with the person or system provisioning that infrastructure. Per-resource tuning should not unexpectedly resize a shared backend.

## Creation, updates and migration

| Kind of change | What to plan |
| - | - |
| Creation-time setting | Include it when creating a disposable resource; verify the native result. |
| Supported mutable setting | Use its documented update API; inspect target state after completion. |
| Runtime connection setting | Apply it to the correct process; account for restarts and rolling overlap. |
| Replacement-only setting | Create a replacement, migrate data or traffic, and retain a rollback path. |
| Different backend | Plan a data migration; changing a tag is not a migration procedure. |

A tag supplied during creation is not a per-request override on subsequent reads or writes. Changing a tag later is not, by itself, a documented capacity-update operation. Removing a tag does not necessarily restore an earlier target setting.

For an existing resource, use its documented native or adapter update path. Avoid competing writers: if provisioning configuration owns a field, change that configuration so reconciliation does not undo your manual change.

## Run a controlled experiment

Cloud Adapter's included agents can help turn a capacity or latency question into one measured comparison. Bring the baseline, selected mapping, proposed control and recovery requirements to [Support Agents](https://docs.tensor9.com/cloud-adapter-early-access/support/agents.md), then use [Tuning with Agents](https://docs.tensor9.com/cloud-adapter-early-access/tuning/agents.md) to define the experiment. Keep the resource owner, spending limits and change approval attached through [Operations with Agents](https://docs.tensor9.com/cloud-adapter-early-access/operations/overview.md).

**1. State the problem**

Define the workload and outcome. For example: reduce backlog during a ten-minute burst without increasing duplicate processing, or keep table write latency within the application's budget.

**2. Record the baseline**

Record adapter version, backend, placement, resource names, effective settings, payload sizes, key distribution and concurrency. Measure completed work, p50/p95/p99 latency, retries, errors and target utilization. Include failures.

**3. Inspect the mapping**

Use [tensor9 explain](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain.md) to inspect the service profile. Use a request preview before a mutation. Identify which resource and field the setting affects.

**4. Change one control**

Use an isolated test deployment. Keep requests, data and the load generator fixed. Include warm-up, steady traffic and a representative burst.

**5. Verify state and behavior**

Read the effective native setting and repeat correctness checks and the workload. An accepted origin request does not prove a target field changed; a changed field does not prove performance improved.

**6. Keep or reverse the change**

Compare the same measurements, including cost drivers. Write the rollback operation before deploying widely. Capacity reductions and validation changes may leave data or work that needs separate recovery.

## Use Explain at both ends of the experiment

Start with a profile explanation:

```bash theme={null}
tensor9 explain \
  -origin aws::1.0.0::dynamodb::table \
  -target azure::1.0.0::cosmosdb::provisioned \
  -fmt Human
```

During testing, capture executed explanations for selected requests using `x-t9-explain: true`. Correlate the request identifiers with target metrics. See [SDK integration](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain-sdk.md) for header injection.

> [!WARNING]
>
> `x-t9-explain: true` executes the request. It is not a dry run. Use Explain preview mode to inspect a mutation without performing it. An explanation or receipt does not replace native resource verification or application-level correctness checks.

## Common mistakes

| Observation | Check before changing capacity |
| - | - |
| More connections made latency worse | Target saturation, connection budget and contention. |
| More capacity did not improve one hot key | Key distribution, serialization and per-partition limits. |
| Lower latency appeared after a change | Whether retries, failures, payloads or request mix changed too. |
| Queue throughput improved but duplicates increased | Visibility duration, acknowledgement timing and idempotency. |
| A tag changed but behavior did not | Whether the operation applies that setting after creation. |
| A native change disappeared | Whether deployment configuration or another reconciler owns the field. |

Continue with [worked examples](https://docs.tensor9.com/cloud-adapter-early-access/tuning/examples.md), [DynamoDB](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-dynamodb.md), [SQS](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-sqs.md) or [S3](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-s3.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.