# ITraceStore

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.itracestore/
> Summary: ITraceStore: The store for persisted spans.

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.Abstractions.dll</code></div>

The store for persisted spans.

```csharp
public interface ITraceStore
```

## Remarks

**An error from this store does not stop the run.**
Observability must not break functionality; the caller
(`RunTraceCollector`) catches and logs errors.

The write path is *sampled*. Writing every span would bottleneck the
database at high volume; the sampling decision belongs to the caller
(`TraconObservabilityOptions`), not the store.

**Tenant behavior is not uniform across this interface's methods.**
[ITraceStore.WriteSpansAsync](/api/tracon.itracestore/#Tracon_ITraceStore_WriteSpansAsync_Tracon_TraceSpanBatch_System_Threading_CancellationToken_) is EXPECTED tenant: it reads
[TraceSpanBatch.TenantId](/api/tracon.tracespanbatch/#Tracon_TraceSpanBatch_TenantId), never the ambient tenant, for the
same reason [IRunStore.AppendEventAsync](/api/tracon.irunstore/#Tracon_IRunStore_AppendEventAsync_Tracon_RunEvent_System_Threading_CancellationToken_) does — the writing
thread may not belong to the trace's own tenant.
[ITraceStore.GetTraceByRunAsync](/api/tracon.itracestore/#Tracon_ITraceStore_GetTraceByRunAsync_System_Guid_System_Threading_CancellationToken_) is AMBIENT tenant: it takes no explicit
tenant parameter and filters by the current `ITenantContext`
internally.

## Methods

### <a id="Tracon_ITraceStore_GetTraceByRunAsync_System_Guid_System_Threading_CancellationToken_"></a> GetTraceByRunAsync\(Guid, CancellationToken\)

Fetches a run's span tree.

```csharp
ValueTask<RunTrace?> GetTraceByRunAsync(Guid runId, CancellationToken cancellationToken = default)
```

#### Parameters

`runId` [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

The run identifier.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[RunTrace](/api/tracon.runtrace/)?\>

The trace; [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) if no record exists.

### <a id="Tracon_ITraceStore_WriteSpansAsync_Tracon_TraceSpanBatch_System_Threading_CancellationToken_"></a> WriteSpansAsync\(TraceSpanBatch, CancellationToken\)

Writes a trace's spans. Can be called multiple times for the same
trace; spans are merged by identifier.

```csharp
ValueTask WriteSpansAsync(TraceSpanBatch batch, CancellationToken cancellationToken = default)
```

#### Parameters

`batch` [TraceSpanBatch](/api/tracon.tracespanbatch/)

The span set to write.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask)

The completion task.