> For the complete documentation index, see [llms.txt](https://docs.fractalworks.io/joule/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fractalworks.io/joule/tutorials/analytics/create-custom-metrics.md).
# Create custom metrics
## Overview
In this tutorial we will learn how to create metrics by **defining a metric family.**
This includes the result table store metrics and the runtime frequency using a policy.
{% hint style="info" %}
One or more metric families can be configured, each has its own management policy.
{% endhint %}
### What this tutorial is about
This tutorial covers the creation, definition and the management of metrics within Joule, providing step-by-step guidance on setting up a complete metrics framework using metric families, policies and table schemas.
### Who this tutorial is intended for
This tutorial is designed for developers and data engineers looking to implement and optimise custom metrics in Joule, particularly those working on data-heavy or KPI-driven applications.
### What we will learn
We will learn how to:
1. Define metric families
2. Build and validate efficient queries
3. Assign stable metric keys
4. Set up target table schemas
5. Manage initial metric images and data storage policies
## Prerequisites
Basic knowledge of SQL, familiarity with metrics generation concepts and access to:
1. DuckDB local installation and understanding how to interact with it, [see the documentation](https://duckdb.org/docs/installation/?version=stable\&environment=cli\&platform=macos\&download_method=package_manager).
2. Import dataset, build query and validate results.
3. Joule platform, follow this tutorial to see how to set Joule up [Getting started](/joule/tutorials/getting-started.md).
## Implementation
### Step 1 - Define a metric family name for the metrics
We need to come up with a naming convention that makes sense and is descriptive for our metric.
#### We should expect this output
### Step 2 - Write and validate our metrics generation query
We will build, validate and optimise metrics query.
* Import dataset, build query and validate results.
* Ensure query performance is optimal and sits below 5 seconds.
#### We should expect this output
### Step 3 - Assign a unique stable metric key
We will assign a stable metrics key which is used to query the target metrics table.
{% hint style="info" %}
A successful metric query must only return either 0 or 1 row.
{% endhint %}
#### We should expect this output
### Step 4 - Define target metrics table schema
Define the target metrics table using the metrics family name as the table name.
#### We should expect this output
### Step 5 - Do you need a metric image on start up?
Some processing requirements need to have initial metric values to work correctly, such as KPIs for example.
For this scenario an initial image of metric family is required and may come from pre-validated data or from a previous run without additional processing steps. This data may need to be imported.
In the event of an import we will need to use the [import feature](/joule/components/analytics/metrics-engine/priming-metrics.md) provided by Joule.
#### We should expect this output
### Step 6 - Finally consider storage requirements
With respect to memory usage we should consider how much historical data we will need to store in-memory.
We can use the [compaction policy](/joule/components/analytics/metrics-engine/manage-metrics.md#compaction-policy-attributes) to delete data that is not needed.
#### We should expect this output
## **What Did We Learn?**
In this tutorial, we learned:
1. How to create and manage metrics within Joule by defining metric families.
2. Writing and validating optimised queries
3. Setting up target table schemas
We also covered best practices for assigning stable metric keys, initialising metric images for specific use cases and managing memory usage with compaction policies.
## **What’s Next?**
With these foundational skills in place, the next steps involve exploring advanced metrics configurations, such as:
1. Creating complex metrics aggregations.
2. Applying more sophisticated data transformation pipelines
3. Integrating real-time observability tools.
Additionally, users can dive into [Joule’s processor SDK](/joule/developer-guides/builder-sdk/processor-api.md) to develop custom processors, further enhancing the metrics functionality to meet specific business requirements.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.fractalworks.io/joule/tutorials/analytics/create-custom-metrics.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.