Tuning Your Adapters

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.

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.

Tuning AWS DynamoDB

Cosmos DB capacity, Firestore updates, Spanner and Bigtable connections, and PostgreSQL sizing.

Tuning AWS SQS

Polling, visibility, retention, FIFO workloads and target backend capacity.

Tuning AWS S3

S3-to-GCS transfer concurrency, lifecycle transitions and cost.

Tuning AWS RDS PostgreSQL

Database capacity, connection budgets, query settings and recovery checks.

Tuning AWS Aurora PostgreSQL

Writer and reader capacity, connection routing and workload isolation.

Tuning AWS ElastiCache

Memory, eviction, client concurrency and engine-specific controls.

Tuning AWS OpenSearch

Index layout, ingestion, search latency and cluster resources.

Tuning AWS Lambda

Warm capacity, execution resources, timeouts and downstream budgets.

Tuning Examples

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.

Resource tuning tags

The tag name has this shape:

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:

{
  "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 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

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.

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.

Inspect the mapping

Use tensor9 explain to inspect the service profile. Use a request preview before a mutation. Identify which resource and field the setting affects.

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.

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.

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:

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 for header injection.

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, DynamoDB, SQS or S3.

Tensor9 Cloud Adapter

How It Works

Getting Started

Configuration

Deployment

Support

Amazon Web Services

Google Cloud

Microsoft Azure

Making Trade-offs

Tuning

Debugging

Testing

Guides

Reference

Tuning Your Adapters

Tuning AWS DynamoDB

Tuning AWS SQS

Tuning AWS S3

Tuning AWS RDS PostgreSQL

Tuning AWS Aurora PostgreSQL

Tuning AWS ElastiCache

Tuning AWS OpenSearch

Tuning AWS Lambda

Tuning Examples

Choose the correct control

Defaults and backend selection

Resource tuning tags

Keep directives separate

Resource ownership matters

Creation, updates and migration

Run a controlled experiment

Use Explain at both ends of the experiment

Common mistakes

Tuning AWS DynamoDB

Tuning AWS SQS

Tuning AWS S3

Tuning AWS RDS PostgreSQL

Tuning AWS Aurora PostgreSQL

Tuning AWS ElastiCache

Tuning AWS OpenSearch

Tuning AWS Lambda

Tuning Examples

​Choose the correct control

​Defaults and backend selection

​Resource tuning tags

​Keep directives separate

​Resource ownership matters

​Creation, updates and migration

​Run a controlled experiment

​Use Explain at both ends of the experiment

​Common mistakes

Choose the correct control

Defaults and backend selection

Resource tuning tags

Keep directives separate

Resource ownership matters

Creation, updates and migration

Run a controlled experiment

Use Explain at both ends of the experiment

Common mistakes