Appending with Tags

Chronicle lets you associate tags with appended events. Tags are stored as event metadata and can be used for categorization, filtering, and concurrency scoping.

Built-in metadata tags

Chronicle maintains built-in metadata tags for event identity and stream routing:

• EventSourceType
• EventSourceId
• EventStreamType
• EventStreamId

You can add custom tags in addition to these built-in tags. For the full list and behavior, see Event Metadata Tags.

Custom tags

Custom tags are simple strings that you provide when appending. They are merged with any static tags defined on the event type.

Append with tags

C#

using Cratis.Chronicle.Events;

[EventType]
public record TaggedOrderPlaced(string CustomerId, decimal Total);

public class TaggedCheckoutService(IEventLog eventLog)
{
    public Task<AppendResult> PlaceOrder(OrderId orderId, string customerId, decimal total)
    {
        return eventLog.Append(
            orderId,
            new TaggedOrderPlaced(customerId, total),
            tags: ["checkout", "priority"]);
    }
}

Kotlin

The Kotlin Chronicle client does not support this workflow yet.
Its append options do not currently expose dynamic event tags.

Java

The Java Chronicle client does not support this workflow yet.
The JVM append options do not currently expose dynamic event tags.

Elixir

defmodule MyApp.Events.TaggedOrderPlaced do
  defstruct [:customer_id, :total]
end

defmodule MyApp.TaggedCheckoutService do
  alias MyApp.Events.TaggedOrderPlaced

  def place_order(order_id, customer_id, total) do
    Chronicle.append(
      order_id,
      %TaggedOrderPlaced{customer_id: customer_id, total: total},
      tags: ["checkout", "priority"]
    )
  end
end

TypeScript

The TypeScript Chronicle client does not support this workflow yet.
Its append options do not currently expose dynamic event tags.

AppendMany with tags

AppendMany applies the provided tags to each event in the batch.

C#

using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.Events;

public readonly record struct TaggedAccountId(string Value)
{
    public static implicit operator EventSourceId(TaggedAccountId id) => new(id.Value);
}

[EventType]
public record TaggedMoneyWithdrawn(decimal Amount);

[EventType]
public record TaggedMoneyDeposited(decimal Amount);

public class TaggedTransferService(IEventLog eventLog)
{
    public Task<AppendManyResult> Transfer(TaggedAccountId fromAccount, TaggedAccountId toAccount, decimal amount)
    {
        var events = new[]
        {
            new EventForEventSourceId(fromAccount, new TaggedMoneyWithdrawn(amount)),
            new EventForEventSourceId(toAccount, new TaggedMoneyDeposited(amount))
        };

        return eventLog.AppendMany(events, tags: ["transfer", "audit"]);
    }
}

Kotlin

The Kotlin Chronicle client does not support this workflow yet.
Its append-many options do not currently expose dynamic event tags.

Java

The Java Chronicle client does not support this workflow yet.
The JVM append-many options do not currently expose dynamic event tags.

Elixir

defmodule MyApp.Events.TaggedMoneyWithdrawn do
  defstruct [:amount]
end

defmodule MyApp.Events.TaggedWithdrawalFeeCharged do
  defstruct [:amount]
end

defmodule MyApp.TaggedWithdrawalService do
  alias MyApp.Events.TaggedMoneyWithdrawn
  alias MyApp.Events.TaggedWithdrawalFeeCharged

  def withdraw(account_id, amount, fee) do
    Chronicle.append_many(
      account_id,
      [
        %TaggedMoneyWithdrawn{amount: amount},
        %TaggedWithdrawalFeeCharged{amount: fee}
      ],
      tags: ["withdrawal", "audit"]
    )
  end
end

TypeScript

The TypeScript Chronicle client does not support this workflow yet.
Its append-many options do not currently expose dynamic event tags.