diff --git a/docs/customize-pages-dashboards-and-plugins/dashboards/custom-widgets.md b/docs/customize-pages-dashboards-and-plugins/dashboards/custom-widgets.md index 796ac87674..78496cc27a 100644 --- a/docs/customize-pages-dashboards-and-plugins/dashboards/custom-widgets.md +++ b/docs/customize-pages-dashboards-and-plugins/dashboards/custom-widgets.md @@ -313,3 +313,5 @@ The following table lists the identifiers for each custom widget type: | Action card | `action-card-widget` | | Action history | `action-runs-table-widget` | | Markdown | `markdown` | +| AI Agent | `ai-agent` | +| Links | `links-widget` | \ No newline at end of file diff --git a/docs/customize-pages-dashboards-and-plugins/dashboards/data-widgets.md b/docs/customize-pages-dashboards-and-plugins/dashboards/data-widgets.md index 8a3e4c717c..a53ae345be 100644 --- a/docs/customize-pages-dashboards-and-plugins/dashboards/data-widgets.md +++ b/docs/customize-pages-dashboards-and-plugins/dashboards/data-widgets.md @@ -22,7 +22,7 @@ You can choose one of these chart types: You can also filter entities so the aggregation number chart will only apply to a limited set of entities with Port's [Search Rules](/search-and-query/search-and-query.md#rules) ::: -### Time filtering in number charts vs. line charts +

Time filtering in number charts vs. line charts

The value shown in a **number chart** is calculated over **all available entities** of the selected blueprint. By default, it does not apply any time-based filtering. @@ -35,7 +35,7 @@ This difference happens because the two charts are likely working with different To align both charts and ensure consistency in what they reflect, apply a time filter to the number chart that matches the line chart’s time range. This helps prevent confusion and ensures both charts are working with the same scope of data. -#### Display formatting +### Display formatting You can customize how numbers are displayed in number chart by selecting a formatting function: @@ -69,7 +69,7 @@ However, since 5 is closer to 6 than to 8, the widget will be colored yellow - t -### Number chart properties +### Properties | Field | Type | Description | Default | Required | | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------- | @@ -187,12 +187,43 @@ Bar charts illustrate data from entities in your software catalog divided by cat ## Line chart -Line charts visualize trends over time, either by tracking `number` properties of entities or by tracking the entities themselves. +:::info New line chart capabilities +Starting [PLACEHOLDER], the line chart has been enhanced with new capabilities. Existing line charts remain fully functional, backward compatible, and can still be edited through the UI and API. -Port offers three types of line charts: -1. [Property history (single entity)](#1-property-history-single-entity) - displays the values of one or more properties of a single entity. -2. [Aggregate property (all entities)](#2-aggregate-property-all-entities) - displays the aggregated values of one or more properties across all entities of a specific blueprint. -3. [Count entities (all entities)](#3-count-entities-all-entities) - displays either the total count of entities or the average number of entities from a specific blueprint over time. +The new line chart offers greater flexibility by letting you combine multiple line chart types in a single widget. If you want to use these enhanced capabilities, you should create a new line chart. Note that in the API, the new line chart is named `multi-line-chart`. +::: + +Line charts visualize trends over time, either by tracking `number` properties of entities or by tracking the entities themselves. +A single line chart widget can display multiple lines, allowing you to compare different metrics side by side. + +Port offers three types of lines: +1. [Property history (single entity)](#property-history-single-entity) - displays the values of one or more properties of a single entity. +2. [Aggregate property (all entities)](#aggregate-property-all-entities) - displays the aggregated values of one or more properties across all entities of a specific blueprint. +3. [Count entities (all entities)](#count-entities-all-entities) - displays either the total count of entities or the average number of entities from a specific blueprint over time. + +

Creating a line chart

+ +To add a new line chart widget: + +1. **Configure the chart settings**: + - Provide a **title**, **icon**, **description**, and optionally a custom [**empty state text**](#custom-empty-state) for the widget. + +2. **Configure the X axis** (shared across all lines): + - Give the axis a **title**. + - Select a **time interval**, which is the amount of time between each data point. + - Select a **time range**, which determines how far back the chart displays data (maximum 1 year). + +3. **Configure the Y axis title**. + +4. **Add lines**: + - Click `+ Line` to open the line configuration window. + - Choose the chart type and configure its specific settings (see below for details on each type). + - Repeat to add multiple lines to the same chart. + +**Considerations:** + +- **Shared Y axis**: All lines in the chart share a single Y axis scale. When adding multiple lines, make sure you choose comparable metrics to ensure the chart remains meaningful and readable. +- **Line colors**: Even if a property value (such as an enum) has a defined color in Port (e.g., "Failed" → red), the line chart may not use the same color. Line colors may differ from property colors. ### Property history (single entity) @@ -202,24 +233,17 @@ It reflects the state of the catalog **at the chosen time**. Past values are not Unlike other chart types, this chart preserves **past values**, while others always reflect the current state of the catalog and recalculate when data changes. -When creating this type of line chart: +When creating this line type: -1. Choose the **blueprint** you want to visualize. +1. Give the line a **title**. -2. Under the `Y axis` section - - Give the axis a title. - - - Choose the **entity** you want to visualize. - - - Select one or more of the entity's `number` **properties** to visualize. - -3. Under the `X axis` section: - - Give the axis a title. +2. Choose the **chart type**: `Property history`. - - Choose a **time interval**, which is the amount of time between each data point in the chart. +3. Choose the **blueprint** you want to visualize. - - Choose a **time range** for the chart, which is how far back in time the chart will display data (the maximum is 1 year). - Note that the available time ranges differ according to the selected time interval. +4. Choose the **entity** you want to visualize. + +5. Select one or more of the entity's `number` **properties** to visualize. :::tip Specific entity page When creating a line chart in an [entity page](/customize-pages-dashboards-and-plugins/page/entity-page#dashboard-widgets), the chosen entity will be the entity whose page you are on. @@ -242,37 +266,26 @@ Each property will be displayed as a separate line in the chart. This chart type reflects the **current state** of the catalog and recalculate when data changes. -When creating this type of line chart: - -1. Choose the **blueprint** you want to visualize. +When creating this line type: -2. Under the `Y axis` section: - - Give the axis a title. +1. Give the line a **title**. - - Choose one or more of the blueprint's `number` **properties** to visualize. +2. Choose the **chart type**: `Aggregate property`. - - Choose an **aggregation function**, which is the operation to apply to the selected properties across all entities, for each time interval. - The possible values are: - - `average`: The average value of each selected property. - - `median`: The median value of each selected property. - - `sum`: The sum of values in each selected property. - - `max`: The maximum value of each selected property. - - `min`: The minimum value of each selected property. - - `last`: The last value of each selected property. +3. Choose the **blueprint** you want to visualize. - - Optionally, define [additional filters](#chart-filters) in order to include/exclude specific entities from the chart. - For example, you can filter the entities by a specific property value, or by a specific time range. +4. Choose one or more of the blueprint's `number` **properties** to visualize. -3. Under the `X axis` section: - - Give the axis a title. - - - Choose one of the blueprint's `datetime` properties by which to **measure the time** of the chart data. - This can be the entity's creation time, last update time, or any other `datetime` property. +5. Choose an **aggregation function**, which is the operation to apply to the selected properties across all entities, for each time interval. + The possible values are: + - `average`: The average value of each selected property. + - `median`: The median value of each selected property. + - `sum`: The sum of values in each selected property. + - `max`: The maximum value of each selected property. + - `min`: The minimum value of each selected property. + - `last`: The last value of each selected property. - - Choose a **time interval**, which is the amount of time between each data point in the chart. - - - Choose a **time range** for the chart, which is how far back in time the chart will display data (the maximum is 1 year). - Note that the available time ranges differ according to the selected time interval. +6. Optionally, define [additional filters](#chart-filters) to include/exclude specific entities from the chart. For example, here is a line chart displaying the maximum cost of all services over the span of a month, in weekly intervals: @@ -303,40 +316,28 @@ If you choose to break down the chart by a property, each line will represent a This chart type reflects the **current state** of the catalog and recalculate when data changes. -When creating this type of line chart: +When creating this line type: -1. Choose the **blueprint** you want to visualize. +1. Give the line a **title**. -2. Under the `Y axis` section: - - Give the axis a title. +2. Choose the **chart type**: `Count entities`. - - Choose one of the following functions: - - `count`: Counts the number of entities in each time interval. - - `average`: Calculates the average number of entities in each time interval. +3. Choose the **blueprint** you want to visualize. - - Optionally, break down the chart by a specific blueprint `breakdown property`, generating a separate line for each distinct value of that property. - - - Optionally, define [additional filters](#chart-filters) in order to include/exclude specific entities from the chart. - For example, filter the entities by a specific property value, or by a specific time range. +4. Choose one of the following functions: + - `count`: Counts the number of entities in each time interval. + - `average`: Calculates the average number of entities in each time interval. -3. Under the `X axis` section: - - Give the axis a title. - - - Choose one of the blueprint's `datetime` properties by which to **measure the time** of the chart data. - This can be the entity's creation time, last update time, or any other `datetime` property. + The selected time interval determines how the function is calculated. + For example, if the time interval is a week: + - The `count` function will count the total entities that week. + - The `average` function will count the total entities that week and divide it by 7. - - Choose a **time interval**, which is the amount of time between each data point in the chart. - The selected interval also determines how the function is calculated: + The same logic applies to all time intervals: `Hour`, `Day`, `Week`, and `Month` - when using the `average` function, the total entity count will be divided by 60, 24, 7, and 30 respectively. - For example, if the time interval is a week, each data point will be calculated in the following manner: - - The `count` function will count the total entities that week. - - The `average` function will count the total entities that week and divide it by 7. - - The same logic applies to all time intervals: `Hour`, `Day`, `Week`, and `Month` - - when using the `average` function, the total entity count will be divided by: 60, 24, 7, and 30 respectively. - - - Choose a **time range** for the chart, which is how far back in time the chart will display data (the maximum is 1 year). - Note that the available time ranges differ according to the selected time interval. +5. Optionally, break down the chart by a specific **breakdown property**, generating a separate line for each distinct value of that property. + +6. Optionally, define [additional filters](#chart-filters) to include/exclude specific entities from the chart. For example, here is a line chart displaying the average deployment rate over the span of a month, in weekly intervals, broken down by the `status` property (Success and Fail). @@ -506,5 +507,7 @@ The following table lists the identifiers for each data widget type: | ----------- | ---------- | | Number chart | `entities-number-chart` | | Pie chart | `entities-pie-chart` | +| Bar chart | `bar-chart` | | Line chart | `line-chart` | +| New line chart | `multi-line-chart` | | Table | `table-entities-explorer` | \ No newline at end of file