Entity Metrics


Defining metrics

There is not an exact match between Platform metrics and OpenTelemetry metrics so you will need to keep that in mind when choosing what type of metric to use.

Different metric types have different qualities which translates to different capabilities they support in the Platform. For example, the Gauge metric type fits well if the metric values can increase or decrease over time and you want to aggregate them from child entities up to their parent as a sum of the metrics from the children. However, the Guage metric type does not support the concept of an average roll-up when aggregating the metric from the children to the parent.

To achieve an accurate metric aggregation for a metric that should roll-up as an average of the children, up to the parent, you will need to use the “histogram” or “distribution” metric type. Unfortunately, fsoc does not currently support pushing metrics for either of those types.

A metric definition can be a common definition across multiple entity types. You can see this in the UgottaRide solution where the same miles_traveled metric is used in four different entity types.

You can find more details about metrics with the links below.


  Dev Tip When specifying the value for unit for a metric, the best practice is to ensure your unit value is enclosed in curly braces {}.

"unit": "{rpm}"


Add metrics to your solution

  Use the following commands to add new metric definitions to the solution.

fsoc command to add a metric to the solution.
Command Format: fsoc solution extend --add-metric <metric_name>
Command Help: fsoc solution extend -h

Windows Example Commands:

cd C:\fsoc_projects\my_tenant\ugottaride

fsoc solution extend --add-metric miles_per_hour

fsoc solution extend --add-metric miles_traveled

fsoc solution extend --add-metric engine_rpm

fsoc solution extend --add-metric engine_temperature

Unix-Mac Example Commands:

cd /fsoc_projects/my_tenant/ugottaride

fsoc solution extend --add-metric miles_per_hour

fsoc solution extend --add-metric miles_traveled

fsoc solution extend --add-metric engine_rpm

fsoc solution extend --add-metric engine_temperature

What did these fsoc commands do?

  • Created new subdirectories under /fsoc_projects/my_tenant/ugottaride/objects/model
  • Created five entity definition files under /fsoc_projects/my_tenant/ugottaride/objects/model/metrics
    • miles_per_hour.json
    • miles_traveled.json
    • engine_rpm.json
    • engine_temperature.json
  • Updated the manifest.json file to reference the directory and files it created


  Dev Tip If your metric json files have (“attributeDefinitions”: null) in them, then you should remove that line from the json file as it will cause issues when deploying your solution.

image


Add metrics to entities

After you have used the fsoc commands to create new metric definitions, the next step is to manually add a reference to them in the entities. Use the example below for the rider entity. Add the metricTypes section into your entity json files and include the appropriate metrics for each entity.

/fsoc_projects/my_tenant/ugottaride/objects/model/entities/rider.json

{
    "namespace": {
        "name": "ugottaride",
        "version": 1
    },
    "kind": "entity",
    "name": "rider",
    "displayName": "rider",
    "attributeDefinitions": {
        "required": [
            "riderid"
        ],
        "optimized": [ "riderid", "first_name", "last_name", "display_name" ],
        "attributes": {
            "riderid": {
                "type": "string",
                "description": "The unique identifier of the rider"
            },
            "first_name": {
                "type": "string",
                "description": "The first name of the rider"
            },
            "last_name": {
                "type": "string",
                "description": "The last name of the rider"
            },
            "display_name": {
                "type": "string",
                "description": "The name of the rider to display to the driver"
            }                                    
        }
    },
    "lifecycleConfiguration": {
        "purgeTtlInMinutes": 200,
        "retentionTtlInMinutes": 160
    },

    "metricTypes": [
        "ugottaride:miles_traveled"
    ] 
     
}


/fsoc_projects/my_tenant/ugottaride/objects/model/entities/ride.json

    "metricTypes": [
        "ugottaride:miles_per_hour",
        "ugottaride:miles_traveled"
    ]


/fsoc_projects/my_tenant/ugottaride/objects/model/entities/driver.json

    "metricTypes": [
        "ugottaride:miles_per_hour",
        "ugottaride:engine_rpm",
        "ugottaride:miles_traveled"
    ]


/fsoc_projects/my_tenant/ugottaride/objects/model/entities/vehicle.json

    "metricTypes": [
        "ugottaride:miles_per_hour",
        "ugottaride:miles_traveled",
        "ugottaride:engine_rpm",
        "ugottaride:engine_temperature"
    ]


  Dev Tip When adding metrics to your enities with metricTypes, you should consider ordering them in the way that you want the fsoc melt model command to output them in the melt.yaml file it generates.


Next Steps  

We’ll add relationships / associations between the entities we created.

Click here to continue