Wombat Core is the Java library powering Wombat Carbon Tracker.
It is distributed separately in order to:
- make it possible to build custom extensions
- make it possible to run the core engine outside of the quarkus app
The library requires Java 21+ and adding the following in your pom.xml:
<dependency>
<groupId>tech.illuin</groupId>
<artifactId>wombat-core</artifactId>
<version>0.18.0</version>
</dependency>Additionally, some optional (but highly recommended) extension libraries can be added, at the time of this writing this includes wombat-core-module which, as the name suggests, contains a few implementations enabled by default in the Wombat application.
First, you may want to have a look at our concept definition dump which lists the objects Wombat aims at modeling and manipulating.
From there, we can describe the wombat-core library from a more logical point of view ; it consists of a WombatCore split into two hemispheres:
- the
AssetMonitorfor aggregating activity data samples ; it is designed to be triggered periodically in an asynchronous fashion and will coordinate metric polling - the
AssetEvaluatorfor making environmental footprint (and financial cost) estimates based on measured and/or modeled activity data
An overview:
flowchart LR
CORE_SETUP[WombatCore\nSetup]
ASSET_DECLARATION[Asset\nConfiguration]
subgraph SAMPLING[AssetMonitor: Activity Data Sampling]
direction LR
subgraph SOURCE[Wombat Sources]
direction LR
SOURCE_ORCHESTRATOR[Source\nOrchestration]
SOURCE_A[WombatSource A]
SOURCE_B[WombatSource B]
SOURCE_C[WombatSource C]
SOURCE_ORCHESTRATOR-->SOURCE_A
SOURCE_ORCHESTRATOR-->SOURCE_B
SOURCE_ORCHESTRATOR-->SOURCE_C
end
STORAGE_ACTIVITY[(Metrics Store)]
SOURCE==>STORAGE_ACTIVITY
end
CALL{{Evaluation call}}
subgraph ESTIMATION[AssetEvaluator: Activity Data Evaluation]
direction LR
subgraph ACTIVITY[Wombat Activity Resolvers]
direction LR
ACTIVITY_RESOLVER_A[WombatActivity\nResolver A]
ACTIVITY_RESOLVER_B[WombatActivity\nResolver B]
end
subgraph IMPACT_FINOPS[Wombat Cost Resolvers]
direction LR
FINOPS[Cost Resolving]
FINOPS --> COST_EVAL_RESOLVER_A[WombatEvaluation\nResolver C]
FINOPS --> COST_EVAL_RESOLVER_B[WombatEvaluation\nResolver D]
end
subgraph IMPACT_GREENOPS[Wombat Impact Resolvers]
direction LR
GREENOPS[Impact Resolving]
GREENOPS --> IMPACT_EVAL_RESOLVER_A[WombatEvaluation\nResolver A]
GREENOPS --> IMPACT_EVAL_RESOLVER_B[WombatEvaluation\nResolver B]
end
ACTIVITY ==>|GreenOps| IMPACT_GREENOPS
ACTIVITY ==>|FinOps| IMPACT_FINOPS
end
GREENOPS_RESULT{{Multi-criteria Estimate\nkgCO2eq / MJ / kgSbeq}}
FINOPS_RESULT{{Cost Estimate\n€ / $ / ¥}}
%% Cross-Process Data Flows
CORE_SETUP ==> ASSET_DECLARATION
ASSET_DECLARATION ==> SAMPLING
SAMPLING -.-> CALL
CALL ==> ACTIVITY
IMPACT_GREENOPS ==> GREENOPS_RESULT
IMPACT_FINOPS ==> FINOPS_RESULT
classDef configStyle fill:#cfd8dc88,stroke:#78909c,stroke-width:2px,color:#000
classDef samplingStyle fill:#e3f2fd88,stroke:#64b5f6,stroke-width:2px,color:#000
classDef triggerStyle fill:#ef5350ee,stroke:#c62828,stroke-width:2px,color:#fff
classDef activityStyle fill:#ffe0b288,stroke:#ff9800,stroke-width:2px,color:#000
classDef greenopsStyle fill:#e8f5e988,stroke:#81c784,stroke-width:2px,color:#000
classDef finopsStyle fill:#fff9c488,stroke:#fdd835,stroke-width:2px,color:#000
class CONFIG configStyle
class SOURCE samplingStyle
class CALL triggerStyle
class ACTIVITY activityStyle
class IMPACT_GREENOPS greenopsStyle
class IMPACT_FINOPS finopsStyle
class GREENOPS_RESULT greenopsStyle
class FINOPS_RESULT finopsStyle
The WombatCore is configured by way of WombatModules which are declarative structures exposing one or more subcomponents.
There are "core" modules which are shipped as part of the wombat-core-module library, but you can create custom modules in order to accommodate your requirements.
Wombat relies on three fundamental component interfaces representing distinct stages of the collection and evaluation pipeline:
WombatSourceare triggered periodically by theAssetMonitor, they are expected to poll telemetry endpoints (e.g. Kubernetes API, Prometheus metrics, etc.) and returnsMetricDatato be persistedWombatActivityResolverare activity data aggregators. Given anAsset, aTimeRangeand an optionalAssetFilter, it computes a standardized representation ofAssetActivitywithActivityDatadata-points (e.g. CPU nanocores, LLM token counts) from historical metrics or modeled profilesWombatEvaluationResolverare evaluation engines. Given anAssetand its resolvedActivityData, it computes either multi-criteria environmental footprints (AssetImpact) or financial costs (AssetCost).
Core modules provide ready-to-use implementations of asset types and their associated components. For details on shared data structures, time formats, and enums used across module configurations, see the Generic Type Glossary.
Below is a list of currently implemented core modules shipped as part of the wombat-core-module library. Follow the links to each of their dedicated documentation for more information on how to use them.
| Module | Family | Description |
|---|---|---|
tech.illuin.wombat-module.kubernetes-api |
KUBERNETES_CONTAINER |
Connects to Kubernetes cluster APIs to poll CPU and memory resource metrics. |
tech.illuin.wombat-module.kubernetes-static |
KUBERNETES_CONTAINER |
Models static Kubernetes container workloads using node counts and superposed temporal scenarios. |
tech.illuin.wombat-module.llm-prometheus |
LLM |
Queries Prometheus via PromQL for LLM inference telemetry. |
tech.illuin.wombat-module.llm-static |
LLM |
Models static LLM workloads based on annual request profiles. |
tech.illuin.wombat-module.llm-anthropic |
LLM |
Queries the Anthropic Admin usage report on demand for per-model token usage over the evaluated time range. |
tech.illuin.wombat-module.llm-vertexai |
LLM |
Queries the VertexAI usage report on demand for per-model token usage over the evaluated time range. |
While WombatModules are allowed to declare specific asset types and introduce a complete pipeline for resolving activity and making impact estimates, most of the time you will only want an override for a single part of the pipeline, like a WombatSource, or a WombatActivityResolver.
For instance, if you need to sample LLM service data from a specific database, you will only be concerned about a WombatSource implementation.
In such cases, the rest of the pipeline will rely on "default components" based on the service family. Basically, for each part of the pipeline described earlier there are two scenarios:
- either the type of the
Assetbeing evaluated requires its own component as declared by its associatedWombatModule, and the engine will use that - or, the type of the
Assetbeing evaluated has no such requirement, in which case the corresponding default for thisAsset's family will be used
At the time of this writing, the wombat-core library ships with the following default component implementations:
For the KUBERNETES_CONTAINER family:
- Activity Resolvers:
KubernetesActivityResolveraggregates historical container and node metrics from a metric store
- Evaluation Resolvers:
BoaviztaEvaluationResolverestimates multi-criteria environmental impacts (GHG emissions, primary energy, abiotic depletion) for server and container workloads using the Boavizta API
For the LLM family:
- Activity Resolvers:
LLMActivityResolveraggregates historical LLM request activity and token consumption from a metric store
- Evaluation Resolvers:
EcologitsEvaluationResolverestimates multi-criteria environmental footprints for AI/LLM inferences using EcoLogits
Following are a few code samples demonstrating basic usage of the wombat-core library.
Wombat, the application, obviously ships with its own WombatCore configured from core-modules and eventually user-provided extensions.
But it is also possible to create your own WombatCore for use outside the application!
First, you will need to implement one critical component: the WombatContextProvider.
The role of the WombatContextProvider is to inform the WombatCore about the systems it needs to monitor and manipulate. The context can expose:
- one or several
Environment: you can think of anEnvironmentas a "complete" application with app containers, db containers, LLM services being used, etc. - each of these
Environmentcan have one or severalAssetregistered in it: anAssetis a method of modeling services we need to measure/estimate, for example you can have anAssetthat will make Wombat observe containers in a given K8S namespace
For instance, the AssetMonitor's job (see above) is to ask the WombatContext to list the Asset it knows about, and for each monitorable asset, it will trigger the corresponding module's WombatSource at a regular interval.
Wombat, the application ships with its own WombatContextProvider implementation backed by a database, which could be replicated fairly easily. For the sake of this documentation we'll do simpler than that and compute a static context:
public class MyContextProvider implements WombatContextProvider
{
@Override
public WombatContext provide()
{
return new ResolvedContext(new Environment("sample", List.of(
/* Create your assets here (e.g. Kubernetes, LLM), see #core-modules */
)));
}
}Next, the other critical component is the WombatMetricPersister: this is where sampled data-points go when sources are triggered. wombat-core ships with an in-memory Micrometer-based implementation which you can use.
As with any other Micrometer setup, the metrics can be plugged into a prometheus or other time-series database of your choice.
/* io.micrometer.core.instrument.MeterRegistry meterRegistry */
WombatMetricPersister metricPersister = new MicrometerMetricPersister(meterRegistry);On the other end of the persistence equation, are the components responsible for reading the data-points:
KubernetesMetricResolverfor resolving kubernetes-container related data samplesLLMMetricResolverfor resolving LLM services related data samples
Similarly, wombat-core ships with in-memory Micrometer-based implementations, while the Wombat, the application has database-backed implementations.
/* io.micrometer.core.instrument.MeterRegistry meterRegistry */
KubernetesMetricResolver k8sMetricResolver = new MicrometerKubernetesMetricResolver(meterRegistry);
LLMMetricResolver llmMetricResolver = new MicrometerLLMMetricResolver(meterRegistry);/* tech.illuin.wombat.core.connector.boavizta.connector.BoaviztaClient boaviztaClient */
/* tech.illuin.wombat.core.connector.ecologits.connector.EcologitsClient ecologitsClient */
try (WombatCore core = new WombatCore(
contextProvider,
metricPersister,
List.of(
new KubernetesAPIModule(),
new KubernetesStaticModule(),
new LLMStaticModule()
),
defaults -> {
defaults.register(KUBERNETES_CONTAINER, new KubernetesActivityResolver(k8sMetricResolver), new BoaviztaEvaluationResolver(boaviztaClient), null);
defaults.register(LLM, new LLMActivityResolver(llmMetricResolver), new EcologitsEvaluationResolver(ecologitsClient), null);
}
)) {
/* The evaluator is stateless, you should reuse it throughout your app ; e.g. make it injectable if applicable */
AssetEvaluator evaluator = core.createEvaluator();
Instant now = Instant.now();
TimeRange range = new TimeRange(now.minus(Duration.ofHours(24)), now);
List<AssetEvaluation> results = evaluator.evaluate(range, AssetFilter.none());
}Custom modules enable tracking domain-specific assets , integrating custom activity modeling or even custom impact/cost resolving. To create a custom module, define an Asset with its profile, implement WombatModule, and provide the relevant resolvers (such as a WombatActivityResolver).
Here is an example of a custom module providing modeled activity data for LLM traffic:
public class MySimulationModule implements WombatModule
{
public static final AssetType TYPE = AssetType.of(
"com.example", "wombat-module", "my-simulated-llm", ActivityRegime.MODELED, ServiceFamily.LLM
);
@Override
public AssetType type() { return TYPE; }
@Override
public Class<? extends Asset> assetClass() { return MySimulationAsset.class; }
@Override
public Optional<WombatActivityResolver> createActivityResolver(WombatContext ctx)
{
return Optional.of(new MySimulationActivityResolver());
}
}
public record MySimulationAsset(
AssetIdentity identity,
MySimulationProfile profile
) implements Asset {
@Override
public AssetType type() { return MySimulationModule.TYPE; }
public record MySimulationProfile(
LLMProvider provider,
String model,
Country location,
long baseTokens
) implements LLMProfile {}
}
public class MySimulationActivityResolver implements WombatActivityResolver
{
@Override
public boolean accept(Asset asset)
{
return asset instanceof MySimulationAsset;
}
@Override
public Optional<AssetActivity> resolve(Asset asset, TimeRange range, AssetFilter filter)
{
MySimulationProfile profile = ((MySimulationAsset) asset).profile();
String serviceId = asset.identity().id();
List<ActivityData> activities = new ArrayList<>();
// Split the target time range into discrete slots matching its requested resolution
for (TimeRange slot : range.split())
{
// Diurnal traffic variation (sinusoidal peak during daytime hours)
int hour = slot.start().atZone(ZoneOffset.UTC).getHour();
double diurnalFactor = 0.5 + 0.5 * Math.sin(Math.PI * (hour - 8) / 12.0);
// Random jitter (±10%)
double jitter = 1.0 + (ThreadLocalRandom.current().nextGaussian() * 0.1);
long simulatedTokens = (long) (profile.baseTokens() * Math.max(0.1, diurnalFactor * jitter));
double simulatedRequests = simulatedTokens / 200.0;
LLMServiceActivity service = new LLMServiceActivity(
profile.provider(),
profile.model(),
profile.location(),
simulatedTokens,
simulatedRequests
);
activities.add(new LLMActivityData(
ActivityRegime.MODELED,
Set.of(serviceId),
slot,
Map.of(serviceId, service)
));
}
return Optional.of(new AssetActivity(
asset.identity(),
activities
));
}
}Once defined, you can register this module in your WombatCore as seen above or in a Wombat app as documented here.
Building the project requires a Java 21+ JDK, in order to compile it:
mvn clean compileRun all tests:
mvn clean testPackage it (as a .jar in target/):
mvn clean packageTo package it without running tests, append -DskipTests:
mvn clean package -DskipTestsThis project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0) ; see the LICENSE file for details.
Copyright (c) 2026 Illuin Technology.