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
| Type | Role |
|---|---|
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. |
GreSampler | Keeps 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. |
TraceHeaders | Writes and reads W3C traceparent in Kafka headers, and builds span links for a batch that mixes many producers (capped). |
GreMetrics | Every 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).
| Type | Role |
|---|---|
Topics, KafkaOptions, ClientSecurity | Topic names, bootstrap and partitions, and TLS or SASL settings applied to every Kafka client |
TopicAdmin.EnsureAsync | Creates transactions, sessions and a compacted suppression topic if missing |
EventPublisher | Idempotent 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, EventFormats | Encoding and decoding in the three supported formats, against the schemas in Schemas/ |
EventMapper | Maps loosely typed fields (camelCase or snake_case) onto events |
DecayedCounter | Bets, stake and seconds that halve every half-life; Apply and Decay |
Deltas | What a transaction or session adds to the counters, and the offset-guard source name |
ProfileStore | The Redis hash per customer and the Lua script that applies a batch atomically and idempotently |
StreamAffinity | Affinity from decayed totals (same log scale and per-customer max as batch) |
ConsumerGroupTool | ResetToTimeAsync (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.