Skip to main content

Shared libraries

Four class libraries are shared by the GRE services. They are deliberately small so that services stay independent.

Kaleido.Gre.Contracts​

The wire types: TransactionEvent, SessionEvent, IngestResult, GameActivity, CustomerActivity, ActivityPage, ActivityStats. No dependencies, so any producer can reference it without pulling in the rest of the platform. See Data ownership.

Kaleido.Gre.Hosting​

ServiceKey.Require(config) reads Service:ApiKey and refuses to start if it is missing or under 16 characters. app.UseServiceKey(key) adds the middleware that rejects every request except /health without the right X-Api-Key. See Security.

Kaleido.Gre.Telemetry​

TypeRole
GreTelemetry.AddGreTelemetry(serviceName, defaultSampleRatio)Registers tracing (ASP.NET Core, HttpClient, Npgsql, the Kaleido.Gre source), metrics and logging over OTLP. Nothing is exported unless OTEL_EXPORTER_OTLP_ENDPOINT is set.
GreSamplerKeeps a share of new traces, always follows a parent's decision, and never starts a trace from a lone Redis or database call, so background polling does not flood the data.
TraceHeadersWrites and reads W3C traceparent in Kafka headers, and builds span links for a batch that mixes many producers (capped).
GreMetricsEvery custom metric in one place: kaleido.gre.ingest.*, kaleido.gre.redis.apply.duration, kaleido.gre.recommend.duration, kaleido.gre.catalogue.*, kaleido.gre.suppression.*, kaleido.gre.builds, kaleido.gre.build.duration, kaleido.gre.activity.events, kaleido.gre.simulator.stream.*.

HTTP spans are named by route template, so customer ids never appear in telemetry. See Observability.

Kaleido.Gre.Stream​

Everything the live path needs, shared by the simulator (producer), ingest (consumer and writer) and recommender (reader).

TypeRole
Topics, KafkaOptions, ClientSecurityTopic names, bootstrap and partitions, and TLS or SASL settings applied to every Kafka client
TopicAdmin.EnsureAsyncCreates transactions, sessions and a compacted suppression topic if missing
EventPublisherIdempotent producer (acks=all, LZ4, 20 ms linger, 256 KB batches, 500,000-message queue) keyed by customer, with traceparent headers and back-pressure on a full queue
IEventFormat, JsonFormat, AvroFormat, ProtobufFormat, EventFormatsEncoding and decoding in the three supported formats, against the schemas in Schemas/
EventMapperMaps loosely typed fields (camelCase or snake_case) onto events
DecayedCounterBets, stake and seconds that halve every half-life; Apply and Decay
DeltasWhat a transaction or session adds to the counters, and the offset-guard source name
ProfileStoreThe Redis hash per customer and the Lua script that applies a batch atomically and idempotently
StreamAffinityAffinity from decayed totals (same log scale and per-customer max as batch)
ConsumerGroupToolResetToTimeAsync (rewind a group to a timestamp after a Redis restore) and Lag

The C# DecayedCounter.Apply and the Lua script must give identical results; StreamStateTests compares them.