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

> Worked tuning scenarios for AWS services, from Cosmos capacity and SQS workers to GCS lifecycle and GKE nodes.

Use these examples to choose a tuning experiment for your workload. Some change a native target field; others use the existing AWS API or an application setting. The snippets explicitly identified as fragments belong inside a larger request.

For complete setup, native verification and rollback, use the [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) and [S3](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-s3.md) tuning articles.

## Choose an experiment

| Workload or symptom | Experiment | What the comparison must include |
| - | - | - |
| DynamoDB writes throttled on provisioned Cosmos | Give a dedicated container a suitable autoscale maximum | RU consumption, hot partitions, throttling, tail latency and capacity cost |
| Small Cosmos workload with uneven traffic | Compare provisioned and serverless in separate test resources | Burst behavior, supported indexes, cost drivers and migration requirements |
| Firestore update-heavy workload | Compare strict updates with eligible blind updates | Native reads/writes and the item-size validation tradeoff |
| Spanner or Bigtable client queueing | Change channel count within documented bounds | Adapter concurrency, target utilization and key distribution |
| PostgreSQL-backed DynamoDB waiting for connections | Compare a small pool increase against the total database budget | All pools, replicas, rolling overlap, locks and target saturation |
| SQS workers repeatedly receive no messages | Use long polling where the backend supports it | Empty receives, receive cost, client timeout and end-to-end job latency |
| SQS work becomes visible while still processing | Set a suitable visibility timeout or extend an active lease | Crash recovery, duplicate handling and total processing duration |
| FIFO queue has a growing backlog | Compare independent message groups | Per-group ordering, duplicate suppression and successful jobs per second |
| Cloud SQL-backed queues compete for capacity | Size the shared database and bound worker concurrency | Aggregate workload, connections, CPU, disk, locks and backlog age |
| S3 uploads stall under parallel traffic | Sweep bounded client concurrency | Completed bytes, errors, retries, memory and p95/p99 latency |
| Old reports are rarely read | Use a supported GCS lifecycle transition | Storage, retrieval and early-deletion costs |
| EKS node pool has unsuitable CPU/memory | Override the GKE machine type | Scheduling, workload latency, quota and replacement requirements |

> [!NOTE]
>
> Tuning fields are service-specific. Use a field only for the exact mapping shown on this page; a field shown for DynamoDB or EKS does not automatically apply to another service.

## DynamoDB to provisioned Azure Cosmos DB

The [provisioned Cosmos DB mapping](https://docs.tensor9.com/cloud-adapter-early-access/service-catalog/aws/databases-storage/dynamodb-table.md#azure-cosmos-db-provisioned) needs a capacity choice for each table-owned container. This `CreateTable` fragment supplies the backend selector and capacity together; the [complete example](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-dynamodb.md) also includes the key schema and attribute definitions:

```json theme={null}
{
  "TableName": "orders",
  "BillingMode": "PAY_PER_REQUEST",
  "Tags": [
    {
      "Key": "t9:backend",
      "Value": "azure::1.0.0::cosmosdb::provisioned"
    },
    {
      "Key": "t9:tuning:container.properties.options.autoscaleSettings.maxThroughput",
      "Value": "40000"
    }
  ]
}
```

`t9:backend` selects the provisioned Cosmos DB mapping. The tuning tag sets the target container's `properties.options.autoscaleSettings.maxThroughput` field, giving `orders` a dedicated autoscale band with a maximum of 40,000 RU/s. These directives do not change the request's DynamoDB billing mode.

Choose a maximum supported by Cosmos DB in the target region. The value must be at least 1,000 RU/s and use 1,000-RU/s increments. Treat 40,000 RU/s as an example, not a recommendation. Verify the effective autoscale maximum on the resulting Cosmos DB container, then measure consumed RUs, throttling, latency and cost under a representative workload.

## SQS: fewer empty receives

For an existing test queue on a backend supporting long polling, set the default wait:

```bash theme={null}
aws sqs set-queue-attributes \
  --queue-url "$SQS_TUNING_QUEUE_URL" \
  --attributes '{"ReceiveMessageWaitTimeSeconds":"20"}'

aws sqs receive-message \
  --queue-url "$SQS_TUNING_QUEUE_URL" \
  --wait-time-seconds 20 \
  --max-number-of-messages 10
```

Set `AWS_ENDPOINT_URL_SQS` to the adapter endpoint first, as shown in [the SQS setup](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-sqs.md). That setup captures the created queue's URL in `SQS_TUNING_QUEUE_URL`; it is a shell variable containing a command result, not an SDK configuration setting. Run these commands in the same shell. The receive request can override the queue's default wait. Use a client read timeout longer than the wait, allowing for network overhead. A longer wait does not mean a message already available must wait for the entire interval.

Compare empty receives and completed work for the same arrival rate. Long polling can reduce polling overhead; it does not increase database capacity or change the queue's delivery guarantee. Restore the previous queue attribute to reverse this change.

## SQS: allow time for processing

For a PostgreSQL-backed test queue with jobs that may run for several minutes, use the endpoint and queue URL from [the PostgreSQL setup](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-sqs.md#postgresql-for-delayed-or-long-running-work). Set `SQS_TUNING_QUEUE_URL` to that queue's returned URL before running these commands; do not reuse the Pub/Sub queue from the previous example:

```bash theme={null}
aws sqs set-queue-attributes \
  --queue-url "$SQS_TUNING_QUEUE_URL" \
  --attributes '{"VisibilityTimeout":"900"}'

aws sqs get-queue-attributes \
  --queue-url "$SQS_TUNING_QUEUE_URL" \
  --attribute-names VisibilityTimeout
```

A 900-second visibility window gives a worker 15 minutes before unacknowledged work becomes eligible for another receive. The trade-off is slower recovery if a worker crashes immediately. For variable-duration work, compare a shorter initial visibility window with explicit lease extensions. Always make processing idempotent and delete the message only after successful completion.

Do not copy this value to Pub/Sub or Service Bus: their mapped visibility bounds differ. See the [backend table and lease examples](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-sqs.md).

## DynamoDB: change a pool without overloading PostgreSQL

The DynamoDB PostgreSQL backend's process setting is:

```bash theme={null}
export T9_POSTGRES_POOL_SIZE=12
```

Set it in the environment that starts the adapter, not in the application's AWS client process. Restart the relevant adapter processes through the deployment's normal rollout. This is not a table tag, and it does not increase the database's connection limit.

If four adapter processes each have two backend pools, this setting can permit up to `4 × 2 × 12 = 96` pooled connections. A rollout with one additional process adds up to 24 more. Reserve connections for administration and other workloads before choosing the pool size.

Compare connection wait, query latency, locks and database CPU. If a larger pool just increases contention, revert the process setting and investigate the database or query workload. See [DynamoDB on PostgreSQL](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-dynamodb.md) for the full capacity example.

## S3: compare transfer concurrency before changing storage

Use the bounded upload script in [Tuning AWS S3](https://docs.tensor9.com/cloud-adapter-early-access/tuning/aws-s3.md). It compares one, four and eight workers, retains the test prefix for inspection, and verifies every object body after the measured upload phase.

Keep payload size and retries fixed. More completed objects per second is useful only if errors, tail latency and resource usage stay within your application's requirements. Run the test from the intended deployment location before using its numbers for production planning.

## EKS node group to a GKE node pool

For the EKS control-plane mapping to GKE, `t9:tuning:config.machineType` selects the GKE node pool's machine type through the `CreateNodegroup` request's tag map:

```json theme={null}
{
  "t9:tuning:config.machineType": "n2d-standard-4"
}
```

This overrides the target machine choice. It does not rewrite the origin request's `instanceTypes`: the origin description preserves what the application requested while the target node pool uses the explicit override. Verify the node pool's effective configuration rather than inferring it from the origin instance-type name.

Check that the target machine type is available and suitable for your region and workload. Selecting a type does not establish quota, capacity, performance or a cost improvement. Compare the same workload against the default mapping, including scheduling requirements and error rates. This example does not promise that an existing node pool can be retuned without replacement.

For a complete `CreateNodegroup` request, put that map in its `tags` field alongside the normal cluster, node group, role and subnet arguments. Keep ordinary resource tags in the same map. Inspect the resulting GKE node pool and run representative pods before moving traffic; an origin `DescribeNodegroup` alone cannot prove which target machine type was selected.

See the [EKS service profile](https://docs.tensor9.com/cloud-adapter-early-access/service-catalog/aws/compute-containers/eks-cluster.md) for target-specific node group behavior. Do not copy `config.machineType` to AKS or another backend simply because that backend also has virtual machines.

## Record a useful result

Ask your included [support agent](https://docs.tensor9.com/cloud-adapter-early-access/support/agents.md) to organize the baseline, candidate and observations using the record below. [Tuning with Agents](https://docs.tensor9.com/cloud-adapter-early-access/tuning/agents.md) explains how to test a proposed improvement; [Bounded Work and Approval](https://docs.tensor9.com/cloud-adapter-early-access/operations/bounded-work.md) keeps the experiment and its resource changes within the agreed scope. Carry the same record into human support when the result needs further investigation.

Use one record per experiment:

```text theme={null}
Workload: representative operation mix, sizes, keys and arrival pattern
Environment: adapter version, target, region and resource identities
Baseline: requested and effective settings
Change: one field, its units, scope and lifecycle
Correctness: data, ordering, retries and failure cases checked
Before/after: completed work, latency distribution, failures, target utilization
Cost drivers: native operations, storage, capacity and retrievals
Evidence: request identifiers, Explain output and native readback
Rollback: exact previous setting and any separate data recovery required
Decision: keep, revert, or measure again
```

Leave numerical results blank until you measure them. A target API accepting a setting establishes neither a performance gain nor a cost saving.

## Translate the method, not the tag

The general method carries across services: choose a supported target field, send it through the origin operation's supported tag carrier, and inspect the resulting target state. The literal tag does not carry across services unless the selected mapping explicitly supports it.

For a performance-related field, add a repeatable workload and measurements. Do not substitute a descriptive metadata example for a latency, scaling or cost benchmark.

Return to [tuning your adapters](https://docs.tensor9.com/cloud-adapter-early-access/tuning/overview.md) for defaults, scope, acknowledgements and the measurement workflow.


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