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

> Use origin-request tags to express supported target-native choices.

Tuning lets an origin request supply a backend-specific choice that the origin API does not otherwise express. The shared mechanism uses tags named `t9:tuning:<path>`, where `<path>` identifies a supported field in the target API.

For example, a supported tuning field might change a target resource's display name. Other fields can affect runtime behavior. The accepted fields, values and update behavior depend on the service and backend; the prefix does not make every target field writable. The [tuning examples](/cloud-adapter/tuning/examples) are the authoritative list of tuning directives currently documented here.

<Note>
  Tuning fields are service-specific. Use only a path published for the exact origin-to-target mapping in the [examples](/cloud-adapter/tuning/examples).
</Note>

## Supply tuning through the origin API

Use the tag carrier supported by the origin operation, such as a create request's tag map. The adapter interprets recognized tuning tags as target-field directives.

A tag on resource creation is not automatically a per-request override for every later read or write. Likewise, changing a tag after creation only changes the backend if that service implements the corresponding update behavior. Do not assume a data-plane operation accepts tags because its service supports resource tagging elsewhere.

## Decide whether to tune

| Situation                                                        | First action                                                                      |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| The origin request already expresses the behavior you need       | Leave the request unchanged and measure the baseline.                             |
| The target has a required native field with no origin equivalent | Check the examples page for a supported `t9:tuning:` path for that exact mapping. |
| You want to select a different backend                           | Use `t9:backend` where supported; tuning is not backend selection.                |
| You need to acknowledge a known semantic difference              | Use the documented `t9:ack:*` token, not a tuning tag.                            |
| The field is absent from the examples page                       | Do not guess the target path; request coverage or file a product question.        |

Examples must stay mapping-specific. An S3-to-Cloud Storage mapping may publish a target storage-class choice; an SSM-to-Secret Manager mapping may publish a target replication field. Neither example authorizes the same tag on KMS or on a different direction.

Use the exact path and value syntax documented in the example for the selected mapping. Target identity fields and fields managed by the adapter can be restricted. A field's existence in the target cloud's API is insufficient evidence that it can be tuned through the adapter.

## Keep the directive types separate

| Directive            | Purpose                                                                          |
| -------------------- | -------------------------------------------------------------------------------- |
| `t9:tuning:<path>`   | Set a supported target-native field.                                             |
| `t9:backend`         | Select the backend, where supported. It is not a tuning field.                   |
| `t9:ack:unprojected` | Acknowledge named origin attributes that will not be projected, where supported. |
| `t9:ack:degradation` | Acknowledge named semantic losses, where supported.                              |

Acknowledgements require an understanding of the named difference. They do not restore missing behavior. Each service decides which acknowledgement kinds and tokens it supports; do not copy a token from an unrelated service.

`t9:tuning:backend` is not the backend selector. The selector is `t9:backend`.

## Use a measured tuning loop

1. Record the workload, adapter version, backend and current effective settings.
2. Identify one supported field that addresses the observed behavior. Read its scope and constraints.
3. Apply the change to test resources using the supported origin operation.
4. Verify the resulting target setting and repeat the same workload.
5. Compare the outcome and keep or reverse the change using the service's supported update path.

Measure latency, throughput and error rates under comparable conditions. A configuration change alone does not prove a performance improvement. Cost comparisons also need workload volume and the target service's applicable prices.

## Use explain to understand a choice

The [explain interface](/cloud-adapter/debugging/explain) distinguishes the default adaptation from a tuning override and describes relevant limits. Confirm the result by inspecting the test resource's effective target settings.

An explanation of a mapping is different from evidence that a particular live request used it. Preserve relevant resource state and tag history when [debugging](/cloud-adapter/debugging/overview) a tuning issue.