Generate New Metrics

The Trendz Metric Explorer lets you create new metrics from existing telemetries and publish them to ThingsBoard as Calculation Fields. The creation flow moves through four progressive stages.

  ┌──────────────────────────────────────────────────────┐
  │  Metric Definition                                   │
  │  Name + Description + Calculation logic              │
  │  (blueprint — no code yet)                           │
  └───────────────────────┬──────────────────────────────┘
                          │ Implement Field / Create Custom Field
                          ▼
  ┌──────────────────────────────────────────────────────┐
  │  Generated Metric                                    │
  │  Python code, executes in real time                  │
  │  Cannot be used in Trendz views or dashboards        │
  └───────────────────────┬──────────────────────────────┘
                          │ Save Calculation
                          ▼
  ┌──────────────────────────────────────────────────────┐
  │  Native Calculation Field                            │
  │  Integrated into Trendz — available in views         │
  │  (real-time only, no historical points in TB)        │
  └───────────────────────┬──────────────────────────────┘
                          │ Reprocess / Refresh job
                          ▼
  ┌──────────────────────────────────────────────────────┐
  │  Native Calculation Field + ThingsBoard Telemetry    │
  │  Historical data saved — available in dashboards     │
  └──────────────────────────────────────────────────────┘

A Metric Definition is a blueprint for a future metric. It contains:

1. Metric Name — displayed in the Generated Metrics folder in the Fields Section.
2. Metric Description — a short explanation of what the metric measures.
3. How to calculate — step-by-step instructions describing the calculation logic.

A Metric Definition has no implementation — it is purely a textual description of what should be built.

A Generated Metric is an implemented Metric Definition. It contains Python code that executes in real time to produce telemetry values (as a chart or table). A Generated Metric does not store points in ThingsBoard and cannot be used directly in Trendz views — it is a template for a future Calculation Field.

A Generated Metric contains Python code that can be executed to generate values. A Generated Metric does not store points in ThingsBoard.

A Generated Metric can be promoted to a Native Calculation Field, which is fully integrated into the Trendz ecosystem. At this stage the calculation is available in views in real time, but still has no historical telemetry points in ThingsBoard.

See Native Calculation Fields for details.

A Native Calculation Field is integrated into the Trendz ecosystem. At this stage there are still no telemetry points in ThingsBoard. The Calculation Field can be used in real-time Trendz views.

To persist historical data in ThingsBoard, configure a reprocess or refresh job for the Native Calculation Field. Once the job runs, telemetry points are saved to ThingsBoard and become available in dashboards and reports. See Use Metric in ThingsBoard for details.

1. Choose the Entity (Device or Asset profile) for which the metric will be generated.

2. Choose the Item (Device or Asset) on which the metric will be tested.

3. Set the timerange for testing.

4. Click + New Metric.

Choose the business entity for which the metric will be generated. Choose the item on which the metric will be tested. Choose the timerange for testing. Click + New Metric.

After clicking + New Metric you will see two options: AI Suggestions and Create Manually.

The AI agent proposes six metrics based on your telemetries and topology. Click any suggestion to see its Metric Definition (name, description, calculation logic) and use cases. If you are not satisfied with the proposals, click Refresh Ideas to generate a new set. When you find a metric you want, click Implement Field — you will be redirected to the Generated Metric Overview tab.

The AI agent proposes six metrics based on your telemetries and topology. Click a suggestion to see its definition and use cases. Click Refresh Ideas to generate new AI suggestions. Click Implement Field to create the metric. You are redirected to the Generated Metric Overview tab.

Click Create Manually to define a metric yourself, with or without AI assistance.

Without AI — enter only a Field Name and click Create Custom Field. An empty code editor opens; write the metric code yourself.

With AI — check Use AI to create metric and fill in:

Click Create Custom Field — Trendz generates the Python code and opens the Generated Metric Overview tab.

Click Create Manually to switch to the manual creation mode. Without AI: submit a Field Name to create an empty metric. With AI: check Use AI to create metric and fill in the description and computation logic. Click Create Custom Field. You are redirected to the Generated Metric Overview tab with the generated code.

Open the Generated Metrics Overview by clicking any metric in the Generated Metrics folder, or by implementing a metric through the steps above. If you created the metric without AI you will see an empty code editor; otherwise the AI-generated code is already present.

Write or modify metric code in the built-in editor. The syntax is the same as Native Calculation Fields — see Native Calculation Fields for reference.

• Save Changes — persists your edits.
• Cancel Changes — reverts to the last saved version.
• A red cross next to a line indicates a code error.

Save Changes — save the modified code. Cancel Changes — revert to the last saved version. A red cross marks lines with code errors.

Click Run Test to execute the current code against the selected item and timerange. You are redirected to the Overview tab showing the generated values as a chart or table — the same view as a regular metric. See Overview Tab for details.

Click Run Test to execute the metric code. The result is shown as a chart or table in the Overview tab.

Click the Logs button in the upper-left corner to open the execution log section. Use this to diagnose runtime errors and trace execution.

Click Metric Details to view the Metric Definition from which this metric was created (name, description, and original calculation instructions).

Click Ask AI to open the AI chat. Use it to:

• Ask questions about your code.
• Request rewrites or refactoring.
• Ask the AI to detect and fix bugs.

Send a new message:

Type your message in the text field. Review the updated code with AI-applied changes.

Review code generated in a previous interaction:

Click a past message to review the code generated at that point. The code generated after the selected message is shown.

Edit a previous message to rerun it with changes:

Click Edit next to the message you want to modify. Modify the text and confirm the update. Review the code regenerated with your updated message.

Clear chat history:

Click Clear History. Confirm the action by clicking Clear. The chat history is cleared.

To use the metric in Trendz views and ThingsBoard, save it as a Native Calculation Field:

1. Click Save Calculation.

2. Enter the Calculation Name (label shown in Trendz) and Calculation Key (key used in ThingsBoard).

3. Click Save.

The Calculation Field is now saved in Trendz but has no telemetry points in ThingsBoard yet.

Click Save Calculation. Enter the Calculation Name and Calculation Key. Click Save. The Calculation Field is saved in Trendz but has no ThingsBoard telemetry yet.

To save historical data to ThingsBoard, run a Reprocess Task:

1. Click Run to start the process.

2. Select the time range — defines which period of data is saved to ThingsBoard.

3. Choose the items — select the current item, all items, or a specific subset.

4. Click Run to begin.

5. Wait for the task to complete. You can navigate to other metrics while it is running.

Click Run to start the reprocess task. Select the time range for reprocessing. Choose which items to include in the save operation. Click Run to begin the task. Wait for the task to complete. You can navigate away while it runs.

If the metric has an associated Calculation Field, click Open Calculation to open it directly.

Click Open Calculation to open the associated Calculation Field. The associated Calculation Field opens.

When the metric and its Calculation Field diverge, a warning banner appears:

• “Calculation field is not synced with the metric” — the Calculation Field code was modified directly.
• “Calculation field is outdated and needs to be updated” — the metric itself was changed after the Calculation Field was created.

"Calculation field is not synced with the metric" — the CF code was modified directly. "Calculation field is outdated and needs to be updated" — the metric changed after CF creation.

To resolve the divergence, click Save calculation and choose:

• Update existing calculation — overwrites the current Calculation Field with the metric code.
• Create new calculation — creates a new Calculation Field; the metric becomes associated with the new one.

Click Save calculation. Update existing calculation — overwrites the current Calculation Field. Create new calculation — creates a new Calculation Field.

1. Click Change Name next to the metric name.
2. Enter the new name.
3. Click Save.

Click Change Name next to the metric name. Enter the new name and click Save. The metric name is updated.

1. Click Delete next to the metric name.
2. Click Delete again to confirm.

Click Delete next to the metric name. Click Delete again to confirm. The metric is deleted.

The Statistics, Time Patterns, and Range Analysis tabs are available for a generated metric only if:

1. The metric has an associated Native Calculation Field, and
2. That Calculation Field has telemetry data in ThingsBoard for the selected timerange.

If no Calculation Field exists yet, you will be prompted to create one:

If no Calculation Field exists, you are prompted to create one. Create a Calculation Field to unlock the analysis tabs.

If a Calculation Field exists but has no data for the selected timerange, you will be prompted to run a reprocess job:

If the Calculation Field has no data for the timerange, you are prompted to reprocess. Run the reprocess job to save data points to ThingsBoard.

Once telemetry is saved, all tabs show the generated data:

See Tabs Section for a full description of each tab.

• Use Manual mode with AI for specific custom metrics — give the AI a clear description of the business problem and the desired output, not just a formula.
• Give precise instructions when prompting the AI — instead of “Fix my code”, describe the symptom: “The function returns NaN when temperature is below 0, fix the null check.”
• Check logs first when generated code fails — the log section shows which line caused the error and why.
• Fix timeout errors by reducing how often get_telemetries is called. If it is called inside a loop, ask AI to call it once per device instead. Alternatively, narrow the timerange to reduce the number of data points analyzed. You can also increase the execution timeout via SCRIPT_ENGINE_RUNTIME_TIMEOUT in the Python Executor configuration or via SCRIPT_ENGINE_TIMEOUT in the Trendz configuration properties.
• Save frequently using the Save Changes button — unsaved changes are lost if you navigate away.
• Add comments and logs via AI to improve debuggability: ask the AI to add print() statements at key steps, then review them in the Logs section.