Entity Priorities


Entity priorities

While you might be fortunate enough to see the successful persistence of your entities in the Platform tenant you have deployed your solution to, without the use of entity priorities, that doesn’t mean that you shouldn’t start using them from the very beginning of your solution development process.

Without the use of entity priorities, your risk of having the OTLP payloads dropped by the Platform directly correlates to the increased number of solutions that the tenant is subscribed to.

If your OTLP payloads get dropped, that means no data showing up for your solution. Your OTLP payloads may not get dropped in the tenant that you use for development (likely having a minimal number of subscribed solutions) without the use of entity priorities. However, by not implementing them, you risk pushing your solution to production where consumer tenants are subscribed to an unknown number of solutions that would increase the chance of dropped payloads for your solution.


  Dev Tip Do yourself a solid, use entity priorities from the start. Besides, it’s easy to do in 4 steps:

  1. Create an entity priorities directory and json file
  2. Add a reference to your manifest.json for the new entity priorities directory
  3. Ensure each entity declaration in your MELT payload has the attribute “telemetry.sdk.name” = <value_defined_in_entity_priorities_scope_filter>
    • In our example we are using the value ugottaride in our scope filter below. “scopeFilter”: ”‘ugottaride’.equals(source)”
  4. Search for fsoc-melt and replace with <value_defined_in_entity_priorities_scope_filter> in all the json files of your solution


There can only be one!

The Platform must maintain an optimized and highly scalable ingestion mechanism that can match the details in the OTLP payloads coming in for a given tenant, to a specific entity, in a specific solution domain, out of all the solutions that the given tenant is subscribed to. The resource mapper is the front door for the ingestion on the Platform and it will drop your OTLP payload if it cannot match the resource attributes that describe an entity in the payload to a specific entity, (primary entity match).


Add entity priorities


  Create a new directory named entity-priorities in the directory structure of your solution as seen below.

  Now create a new json file named entity-priorities.json with the contents as seen below.


/fsoc_projects/my_tenant/ugottaride/objects/model/entity-priorities/entity-priorities.json

[
    {
        "namespace": {
            "name": "ugottaride",
            "version": 1
        },
        "kind": "entityPriority",
        "name": "ugottaride_entity_priorities",
        "displayName": "UgottaRide Entity Priorities",
        "description": "UgottaRide Entity Priorities",
        "scopeFilter": "'ugottaride'.equals(source)",
        "entityPriorityOrder": {
            "ugottaride:rider": "1",
            "ugottaride:ride": "2",
            "ugottaride:ride_assign": "3",
            "ugottaride:driver": "4",
            "ugottaride:vehicle": "5"
          
        }
    }
]


  Next we must manually add the declaration in the manifest.json file for the entityPriority object type and directory path as seen below at the bottom of the file.

{
    "manifestVersion": "1.0.0",
    "name": "ugottaride",
    "solutionVersion": "0.0.2",
    "dependencies": [
        "fmm
    ],
    "description": "description of your solution",
    "contact": "the email for this solution's point of contact",
    "homepage": "the url for this solution's homepage",
    "gitRepoUrl": "the url for the git repo holding your solution",
    "readme": "the url for this solution's readme file",
    "objects": [
        {
            "type": "fmm:namespace",
            "objectsDir": "objects/model/namespaces"
        },
        {
            "type": "fmm:entity",
            "objectsDir": "objects/model/entities"
        },
        {
            "type": "fmm:metric",
            "objectsDir": "objects/model/metrics"
        },
        {
            "type": "fmm:resourceMapping",
            "objectsDir": "objects/model/resource-mappings"
        },
        {
            "type": "fmm:associationDeclaration",
            "objectsDir": "objects/model/association-declarations"
        },
        {
            "type": "fmm:associationDerivation",
            "objectsDir": "objects/model/association-derivations"
        },

        
        {
            "type": "fmm:entityPriority",
            "objectsDir": "objects/model/entity-priorities"
        }


    ]
}


  Dev Tip Take careful notice of line 11 in the entity-priorities.json file below.

What does “scopeFilter”: ”‘ugottaride’.equals(source)” really mean?

It means that you are telling the resource mapper to match the contents of your OTLP payloads for your solution to the value of ugottaride which is an exact match to your solution name / namespace. This greatly improves the resource mappers ability to obtain the correct entity mapping, and remember, there can only be one matching entity.

Is that all I need to do to get this to work? No, the resource mapper looks for the value of the ”(source)“ in your OTLP payload in an attribute named “telemetry.sdk.name” where the value should match what is defined in the scopeFilter, in this case ugottaride. This is an attribute you will need to manually add to your mock MELT Yaml file generated by the fsoc utility, otherwise, the fsoc utility will automatically add the “telemetry.sdk.name” attribute with the value of fsoc-melt by default when you use the fsoc melt push command.

image


Next Steps  

We’ll walk through the steps to validate and deploy our solution!.

Click here to continue