Diagnostics and Logging¶

The provider integrates with EF Core's standard logging infrastructure, emitting structured events for query execution, write operations, and index-selection decisions. No provider-specific configuration is required — standard Microsoft.Extensions.Logging wiring is all you need.

Enabling Logging¶

The provider hooks into whatever ILoggerFactory EF Core has available. In an ASP.NET Core application this is automatic: the framework registers a logger factory and EF Core picks it up from the DI container.

Filter to the Microsoft.EntityFrameworkCore category to see provider events without noise from the rest of the framework:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft.EntityFrameworkCore": "Information"
    }
  }
}

To see index-selection decisions (the DYNAMO_IDX* codes), the Microsoft.EntityFrameworkCore.Query sub-category must be at Information or lower. The Microsoft.EntityFrameworkCore prefix covers this sub-category, so the filter above is sufficient.

Quick development shortcut — wire logging directly on the DbContextOptionsBuilder without touching the DI container:

protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    optionsBuilder
        .UseDynamo(...)
        .LogTo(Console.WriteLine, LogLevel.Information);
}

LogTo accepts any Action<string> and applies a minimum level filter. It is meant for development and test contexts, not production deployments.

OpenTelemetry Tracing¶

The provider does not create OpenTelemetry spans or a separate EF-query Activity. For request-level tracing, enable the AWS SDK for .NET v4 OpenTelemetry integration in the application before creating DynamoDB clients or DbContext instances. The SDK then emits telemetry for the provider's DynamoDB requests.

Install the AWS instrumentation and an exporter in the application project:

dotnet add package OpenTelemetry.Instrumentation.AWS
dotnet add package OpenTelemetry.Exporter.Console

Configure tracing once during application startup. Replace the Console exporter with your chosen exporter in production:

using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .ConfigureResource(resource => resource.AddService("orders-api"))
    .AddAWSInstrumentation()
    .AddConsoleExporter()
    .Build();

// Create DynamoDB clients and DbContext instances after configuring tracing.

AWS SDK telemetry is disabled by default. See the AWS SDK documentation for observability and OpenTelemetry provider configuration, including exporter and downstream-instrumentation options.

What Gets Traced¶

The AWS SDK owns DynamoDB request spans. The provider's query enumeration issues one ExecuteStatement request for each fetched DynamoDB page, so a paginated query can produce multiple request spans. An EF Core execution-strategy retry can issue another SDK request for the same page; AWS SDK retry and HTTP-span detail depends on the SDK telemetry configuration.

If enumeration is canceled or stopped early, the provider does not fetch later pages. Existing SDK spans still show requests that already started. Use command events, DiagnosticListener payloads, response metadata, consumed capacity, and SDK command interception for the EF-specific table, selected-index, limit, capacity, request-id, and cancellation context that request spans do not provide.

Do not treat spans as a safe place for PartiQL text, parameter values, partition or sort keys, or AWS request IDs. The provider does not add those values to spans. Interceptor request and response objects can contain them, so applications that enrich telemetry through interceptors must apply their own data-handling policy.

What Gets Logged¶

The provider uses three EF Core logger categories:

Command events fire at runtime, once per query execution or once per write statement.

Query events fire at query compilation time — which, due to EF Core's compiled-query cache, means once per unique query shape, not once per execution. If you run the same LINQ expression 1000 times you will see the index-selection events once, on the first compilation. This is intentional: compilation is the expensive decision point, and repeating the log on every execution would obscure patterns in long-running processes.

Model validation errors and LINQ translation failures are thrown as exceptions and are not emitted as log events.

Event Reference¶

Event IDs are stable across releases. You can use them to filter log output programmatically or in structured logging sinks.

The ConsumedCapacity event fires only when ReturnConsumedCapacity is configured on the options builder, so DynamoDB includes capacity in the response.

Command Events¶

Command events cover the full lifecycle of a query or write reaching DynamoDB: the PartiQL text that was generated, the request parameters sent to the ExecuteStatement API, and the response metadata returned.

ExecutingPartiQlQuery — 30100¶

Fires once per query execution, immediately before the first ExecuteStatement HTTP call. Emits the table name and the full PartiQL statement that will be sent:

info: Microsoft.EntityFrameworkCore.Database.Command[30100]
      Executing DynamoDB PartiQL query for table 'Orders'
      SELECT "PK", "SK", "$type", "Status", "Total" FROM "Orders"
      WHERE "PK" = ?

This is the primary tool for verifying LINQ translation. If you see a full table scan when you expected a targeted key lookup, this event tells you what PartiQL was produced and confirms whether the WHERE clause reflects your intent.

ExecutingExecuteStatement — 30101¶

Fires immediately before each HTTP call to DynamoDB. A single query may produce multiple ExecutingExecuteStatement events if the result spans more than one DynamoDB page:

info: Microsoft.EntityFrameworkCore.Database.Command[30101]
      Executing DynamoDB ExecuteStatement request (limit: 25, nextTokenPresent: False, seedNextTokenPresent: False)

Fields:

The limit value is set by a query-level Limit(n) call or by ToPageAsync(limit, token). If it is null and your query can return many items, you will typically see multiple round-trips as the provider auto-pages through DynamoDB results.

ExecutedExecuteStatement — 30102¶

Fires after each HTTP response, paired with the preceding ExecutingExecuteStatement:

info: Microsoft.EntityFrameworkCore.Database.Command[30102]
      Executed DynamoDB ExecuteStatement request (itemsCount: 25, nextTokenPresent: True)

Diagnostic payload fields include itemsCount, nextTokenPresent, elapsed, commandId, requestId, limit, seedNextTokenPresent, and consumedCapacity. The log message keeps the older concise shape for compatibility; use DiagnosticListener or structured diagnostics when you need request id, elapsed time, or consumed capacity.

If itemsCount is less than limit and nextTokenPresent is still True, DynamoDB reached its internal 1 MB page cap before filling your requested page size. The provider will automatically issue another request.

ExecuteStatementFailed — 30112¶

Fires when an ExecuteStatement request fails with a non-cancellation exception:

fail: Microsoft.EntityFrameworkCore.Database.Command[30112]
      Failed executing DynamoDB ExecuteStatement request (requestId: ..., elapsed: 12.34ms)

The payload includes the thrown exception, elapsed, commandId, AWS requestId when available, limit, nextTokenPresent, and seedNextTokenPresent. Failed page requests propagate the original exception to query enumeration; the provider does not convert them to empty pages. Canceled query requests surface through EF Core's QueryCanceled diagnostic event instead of ExecuteStatementFailed.

Query Events¶

ScanLikeQueryDetected — 30111¶

Fires when DynamoEventId.ScanLikeQueryDetected is configured to log and a scan-like read continues:

warn: Microsoft.EntityFrameworkCore.Query[30111]
      Scan-like DynamoDB query detected for table 'Orders' on base table: missing equality or IN predicate on partition key 'PK'. Add an equality or IN predicate on the active partition key and at most one sort-key key condition, configure ConfigureWarnings for DynamoEventId.ScanLikeQueryDetected, or append .AllowScan() for an intentional per-query scan.

By default, the same message is thrown as an InvalidOperationException before PartiQL generation or ExecuteStatement. The provider registers this event as an explicit throwing warning, so ConfigureWarnings(w => w.Default(...)) does not override it. Use ConfigureWarnings with DynamoEventId.ScanLikeQueryDetected to Log, Ignore, or Throw this event explicitly.

The payload contains message, matching the rendered warning text.

ExecutingPartiQlWrite — 30110¶

Fires for each write operation (INSERT, UPDATE, or DELETE) before it is sent to DynamoDB:

info: Microsoft.EntityFrameworkCore.Database.Command[30110]
      Executing DynamoDB PartiQL write for table 'Orders'
      INSERT INTO "Orders" VALUE {'PK': ?, 'SK': ?, '$type': ?, 'Status': ?, 'Total': ?}

This event fires per-statement, not per-batch. When a SaveChangesAsync call produces multiple write operations — whether transactional or non-transactional — each one generates its own ExecutingPartiQlWrite event before the batch is submitted.

Use this event to verify that complex properties, primitive collections, and discriminator values are being serialized into the expected PartiQL parameter positions.

Write request lifecycle — 30113, 30114, 30115, 30116¶

The provider also logs request-level write diagnostics around actual AWS SDK calls. These events are separate from ExecutingPartiQlWrite, which remains statement-level for compatibility.

Request payloads include operation kind (ExecuteStatement, ExecuteTransaction, or BatchExecuteStatement), statement count, provider command id, elapsed time, AWS request id when available, and consumed capacity when DynamoDB returns it.

For BatchExecuteStatement, per-statement Error values are not logged as command failures: the AWS command succeeded, then the provider reports returned statement errors as a warning and keeps normal SaveChanges exception/concurrency behavior. DynamoDB can return HTTP success while some batch statements failed; treat this warning as a per-item failure signal, not a transport failure.

SDK Command Interception¶

IDynamoDbCommandInterceptor provides application callbacks around AWS SDK calls issued for query pages and SaveChanges writes. Register an interceptor through normal EF Core options:

using EntityFrameworkCore.DynamoDb.Diagnostics;

optionsBuilder.AddInterceptors(new MyDynamoDbCommandInterceptor());

Derive from DynamoDbCommandInterceptor and override the callbacks for ExecuteStatement, ExecuteTransaction, or BatchExecuteStatement. Each command has executing, executed, canceled, and failed callbacks. Query callbacks occur once per DynamoDB page; retry attempts receive separate callbacks with page and attempt numbers in the event data.

Interceptors registered in EF Core's internal service provider run before interceptors registered through AddInterceptors(...). Callbacks cannot suppress SDK calls, replace responses, or configure retries.

Interceptor event data exposes the AWS SDK request and response objects. These can contain PartiQL text, parameter values, keys, and returned item data. Do not mutate these objects or write sensitive values to logs, traces, or metrics.

Interception covers provider calls in query paging and SaveChanges. Database lifecycle operations and calls made through context.Database.GetDynamoClient() are not intercepted.

Index Selection Events¶

These events are emitted by the query compiler during index-selection analysis. Because they fire at compilation time, they appear once per unique query shape, not once per execution.

Index selection runs when automatic index selection is enabled via DynamoAutomaticIndexSelectionMode. Setting the mode to Off suppresses all DYNAMO_IDX* events except DYNAMO_IDX004 (explicit .WithIndex(...) hints) and DYNAMO_IDX006 (explicit .WithoutIndex() hints), which always fire.

When multiple targeted candidates are evaluated and rejected, DYNAMO_IDX005 rejection events appear first, followed by the final outcome event (DYNAMO_IDX001, DYNAMO_IDX002, or DYNAMO_IDX003). Candidates whose partition key is not constrained by the query are not treated as rejections; reads that also fail to constrain the active source key may be reported by ScanLikeQueryDetected instead. Enable Information level logging for the Query category to see the full decision trail.

DYNAMO_IDX001 — NoCompatibleSecondaryIndexFound (Warning)¶

At least one secondary index was targeted by the predicate, but every targeted candidate failed a later safety gate. The query will use the base table.

This event is not emitted for unkeyed reads such as ToListAsync() or predicates that do not constrain any configured secondary-index partition key. Those shapes stay on the base table; when they also fail to constrain the active source key, ScanLikeQueryDetected may report the scan-like read. Review the preceding DYNAMO_IDX005 rejection diagnostics to see why the targeted index candidates were rejected, then either adjust the query/index shape or confirm that running against the base table is acceptable for this access pattern.

Use EF Core warning configuration to escalate or suppress this warning:

options.ConfigureWarnings(w =>
    w.Throw(DynamoEventId.NoCompatibleSecondaryIndexFound));

DYNAMO_IDX002 — MultipleCompatibleSecondaryIndexesFound (Warning)¶

Multiple secondary indexes on the table are equally suitable. The message lists the tied index names. The query falls back to the base table.

Use an explicit .WithIndex("IndexName") hint to resolve the ambiguity. The tied index names appear in the message, so you can pick the one that best fits the access pattern.

Use EF Core warning configuration to suppress this warning when the fallback is intentional:

options.ConfigureWarnings(w =>
    w.Ignore(DynamoEventId.MultipleCompatibleSecondaryIndexesFound));

DYNAMO_IDX003 — SecondaryIndexSelected (Information)¶

Automatic selection chose a single compatible index. The query will be rewritten to target it. Confirm that the selected index and table match your intent:

info: Microsoft.EntityFrameworkCore.Query[30106]
      Index 'ByStatus-index' on table 'Orders' was auto-selected.

In On mode the message reads "was auto-selected" and the query is rewritten to target the index. In SuggestOnly mode the message reads "would be auto-selected if automatic index selection were On" and the query is not rewritten — useful for auditing which indexes would fire without changing production query routing.

DYNAMO_IDX004 — ExplicitIndexSelected (Information)¶

The query used an explicit .WithIndex("IndexName") hint and the provider resolved it successfully:

info: Microsoft.EntityFrameworkCore.Query[30107]
      Index 'ByStatus-index' on table 'Orders' was explicitly selected via WithIndex().

DYNAMO_IDX005 — SecondaryIndexCandidateRejected (Information)¶

A targeted candidate index was evaluated and eliminated. The rejection reason is included in the message:

info: Microsoft.EntityFrameworkCore.Query[30108]
      Index 'ByCategory-index' on table 'Orders' was rejected: predicate contains an unsafe OR that would produce incorrect results.

Common rejection reasons:

• Predicate contains an unsafe OR that would produce incorrect results
• Index projection type is not ALL (only ALL projection is auto-selected)

Indexes whose partition key is not constrained by equality or IN are skipped silently rather than reported as rejections. These events appear before the final outcome event and give you visibility into why specific indexes were ruled out.

DYNAMO_IDX006 — ExplicitIndexSelectionDisabled (Information)¶

The query used .WithoutIndex() to suppress automatic index selection. The query will run against the base table regardless of matching indexes:

info: Microsoft.EntityFrameworkCore.Query[30109]
      Index selection was suppressed for table 'Orders' by '.WithoutIndex()'. The query will execute against the base table.

Capacity Events¶

ConsumedCapacity — 30117¶

Fires after DynamoDB reports consumed capacity for a query page or a write request. It lands in the Microsoft.EntityFrameworkCore.DynamoDB.Capacity category, so you can route capacity tracking independently of command logs:

optionsBuilder.LogTo(
    Console.WriteLine,
    LogLevel.Information,
    DbLoggerCategory.Capacity.Name);

The message reports the total estimated capacity units and how many consumed-capacity entries were returned. The ConsumedCapacity property on the event data carries the raw per-table/index entries. This event fires only when ReturnConsumedCapacity is configured on the options builder; otherwise DynamoDB omits capacity and no event is emitted.

Interpreting Pagination Logs¶

Each DynamoDB page produces a before/after pair of ExecutingExecuteStatement and ExecutedExecuteStatement events. Reading the pairs together tells you exactly what happened on each round-trip.

Single page — query returned all results in one call:

info: ...Database.Command[30100]
      Executing DynamoDB PartiQL query for table 'Orders'
      SELECT "PK", "SK", "$type", "Status", "Total" FROM "Orders" WHERE "PK" = ?

info: ...Database.Command[30101]
      Executing DynamoDB ExecuteStatement request (limit: 25, nextTokenPresent: False, seedNextTokenPresent: False)

info: ...Database.Command[30102]
      Executed DynamoDB ExecuteStatement request (itemsCount: 18, nextTokenPresent: False)

18 items came back, no continuation token — done in one round-trip.

Multiple pages — DynamoDB hit its 1 MB internal cap:

info: ...Database.Command[30101]
      Executing DynamoDB ExecuteStatement request (limit: 25, nextTokenPresent: False, seedNextTokenPresent: False)

info: ...Database.Command[30102]
      Executed DynamoDB ExecuteStatement request (itemsCount: 12, nextTokenPresent: True)

info: ...Database.Command[30101]
      Executing DynamoDB ExecuteStatement request (limit: 25, nextTokenPresent: True, seedNextTokenPresent: False)

info: ...Database.Command[30102]
      Executed DynamoDB ExecuteStatement request (itemsCount: 6, nextTokenPresent: False)

The first page returned only 12 items even though the limit was 25 — DynamoDB evaluated more than 1 MB of data and stopped early. The provider fetched the continuation automatically and got the remaining 6 items. Total: 18 items in two round-trips.

If you see many round-trips with nextTokenPresent: True, your filter is very selective relative to the data stored in DynamoDB (or the index). Either apply Limit(n) / ToPageAsync(limit, ...) to bound per-request evaluation, or restructure the query to target a narrower key prefix.

Response Metadata¶

After a tracking query executes, the raw ExecuteStatementResponse from each DynamoDB page is accessible on the entity entry. No-tracking queries do not populate this.

var order = await context.Orders
    .Where(x => x.Pk == "USER#42" && x.Sk == "ORDER#7")
    .FirstAsync();

var response = context.Entry(order).GetExecuteStatementResponse();

// Always populated — include in AWS support tickets and distributed traces
var requestId = response?.ResponseMetadata.RequestId;
logger.LogInformation("DynamoDB request {RequestId}", requestId);

// Only populated when ReturnConsumedCapacity was set on the request
var capacity = response?.ConsumedCapacity;

Page semantics¶

• Entities from the same DynamoDB page share the same response object reference.
• Entities from different pages hold different response objects.
• The NextToken on a non-last-page response has already been consumed by the provider for internally auto-paged queries — do not use it for manual pagination.

These semantics let you correlate read cost and request ID per page when your query returns results from multiple round-trips.

ConsumedCapacity¶

ConsumedCapacity is null unless provider options request it and DynamoDB returns it. Configure this once on the provider options:

optionsBuilder.UseDynamo(options => options
    .DynamoDbClient(client)
    .ReturnConsumedCapacity(ReturnConsumedCapacity.TOTAL));

ReturnConsumedCapacity.TOTAL reports table-level capacity. ReturnConsumedCapacity.INDEXES asks DynamoDB for table and index capacity details where the API supports them. Read diagnostics expose a single ConsumedCapacity; write request diagnostics expose a list because transaction and batch APIs can return multiple capacity entries.

Model Validation Errors¶

Model validation runs during DbContext initialization, before any queries execute. Failures throw exceptions — they are not emitted as EF Core log events.

See Entities and Keys and Secondary Indexes for configuration details.

Translation Failures¶

Unsupported LINQ operators throw InvalidOperationException during query translation — before any DynamoDB requests are sent. The exception message includes provider-specific details about the unsupported shape (unsupported aggregates, joins, set operations, offset-style operators, etc.).

Translation failures are not emitted as log events. They propagate as exceptions and surface during development, not in production steady-state.

See Supported Operators and Limitations for the full list of supported and unsupported LINQ shapes.

DiagnosticListener Payloads¶

EF Core also publishes these events through DiagnosticListener using provider-specific EventData payload types:

Use commandId to join request start/completion/failure events in traces. Use AWS requestId for AWS Support cases and to correlate with SDK/service logs.

Inspecting Generated PartiQL¶

Use EF Core's ToQueryString() to inspect generated PartiQL without sending a request:

var partiQl = context.Orders
    .Where(o => o.CustomerId == customerId)
    .ToQueryString();

The output includes parameter comments with formatted DynamoDB AttributeValue values followed by the PartiQL text. ToQueryString() is for debugging: it does not execute scan-warning behavior, log command events, or call DynamoDB.

Provider option diagnostics¶

EF Core includes the DynamoDB provider's configured options in its context-options diagnostic summary and debug-info dictionary. The summary lists provider settings such as index selection, transaction limits, consistent reads, consumed-capacity reporting, and table-lifecycle waits.

When you supply an AmazonDynamoDBConfig, the diagnostic output can include its AuthenticationRegion and ServiceURL. The endpoint is always reduced to its scheme, host, and port. Credentials, paths, query strings, and URL fragments are omitted. The debug-info keys use the DynamoDB: prefix; object-valued client settings are represented by hash identities rather than object text.

Not Yet Available¶

Sensitive data logging — EnableSensitiveDataLogging() has no effect on DynamoDB provider logs. Parameter values in PartiQL statements are always omitted from log output regardless of this setting.

See Also¶

• Configuration → DbContext Options
• Querying → Index Selection
• Querying → How Queries Execute
• Querying → Pagination
• AWS ExecuteStatement API reference