Configuration

Setting Up a Collator

To utilize the Collator feature you need to configure a FitnessCollator instance. The configuration involves specifying various parameters, including the source of signals, reconciliation keys, buffer period, reconciliation period, and more.

Sample Collator Configuration

kind: FitnessCollator
apiVersion: fitness.orcasio.com/v1alpha3
metadata:
  name: <collator_name>
  namespace: <tenant_ID>
spec:
  collator: collator://fitness.orcasio.net/buffer
  trigger:
    sensor: <sensor_source>
    source: <signal_source>
    bufferPeriod: "<buffer_cron_expression>"
    reconciliationPeriod: "<reconciliation_cron_expression>"
    reconciliationKeys:
      - <reconciliation_key_1>
      - <reconciliation_key_2>
  enabled: true
  mergeTags: true

Parameters Explanation

• name: Name of the Collator instance.
• namespace: Provided tenant ID.
• trigger: Defines the trigger settings for signal collection.
• sensor: Source of sensor data.
• source: Source of signals.
• bufferPeriod: Cron expression indicating how often signals are collected into the buffer.
• reconciliationPeriod: Cron expression for the frequency of grouping and processing signals.
• reconciliationKeys: List of attributes (reconciliation keys) used for signal grouping.
• enabled: Enables or disables the Collator instance.
• mergeTags: Determines whether tags of the collected signals should be merged for the grouped signal.

Example Collator Configuration

kind: FitnessCollator
apiVersion: fitness.orcasio.com/v1alpha3
metadata:
  name: buffer-cron
  namespace: orcas
spec:
  collator: collator://fitness.orcasio.net/buffer
  trigger:
    sensor: sensor://fitness.orcasio.net/kubernetes
    source: deployment
    bufferPeriod: "0 0 0 1 * *" # 1 month
    reconciliationPeriod: "0 * * * * *" # 1 minute
    reconciliationKeys:
      - kind
      - metadata.name
  enabled: true
  mergeTags: true

This configuration creates a FitnessCollator instance named "buffer-cron" within the "orcas" namespace. It will listen to signals from the sensor "sensor://fitness.orcasio.net/kubernetes" with the specified source "deployment". The buffer period is set to one month, meaning that incoming signals will be held in the buffer for a month before being deleted.

The reconciliation period is set to one minute. This means that the Collator will wait for one minute since the arrival of the first signal with a particular reconciliation key (in this case, the combination of "kind" and "metadata.name" attributes from the signal's data) before it groups and processes all signals with the same reconciliation key that arrived within that one-minute window.

The mergeTags parameter is set to true, indicating that tags from the grouped signals will be merged for enhanced analysis.

In summary, this configuration establishes a buffer where incoming signals are held for one month. When a signal is received from the specified sensor and source, the Collator creates a key based on the "kind" and "metadata.name" attributes from the signal's data. It then waits for one minute to group all signals with the same key that arrived within that time window, leading to more meaningful data analysis.

Configure Collator Using API

API Usage:

• URI: (api-URL)/api/inventory/fitness.orcasio.com/v1alpha3/fitnesscollators/<name_of_collator>
• Method: PUT (this is Create or Update a Collator)
• Header (for security): orcas-token: TOKEN (See TOKEN generation details above)

• Request Response:

  SuccessFailure

  {
    "data": [
      {
        "apiVersion": "fitness.orcasio.com/v1alpha3",
        "kind": "FitnessCollator",
        "metadata": {
          "creationTimestamp": "2023-08-23T12:34:56Z",
          "generation": 1,
          "name": "buffer-cron",
          "namespace": "orcas",
          "resourceVersion": "123456789",
          "uid": "abcd-efgh-ijkl-mnop"
        },
        "spec": {
          "collator": "collator://fitness.orcasio.net/buffer",
          "trigger": {
            "sensor": "sensor://fitness.orcasio.net/kubernetes",
            "source": "deployment",
            "bufferPeriod": "0 0 0 1 * *",
            "reconciliationPeriod": "0 * * * * *",
            "reconciliationKeys": ["kind", "metadata.name"]
          },
          "enabled": true,
          "mergeTags": true
        },
        "status": {
          "state": "enabled"
        }
      }
    ]
  }
  

  {
    "error": "the server rejected our request due to an error in our request",
    "message": {
      "apiVersion": "v1",
      "code": 422,
      "details": {
        "causes": [
          {
            "field": "metadata.resourceVersion",
            "message": "Invalid value: 0x0: must be specified for an update",
            "reason": "FieldValueInvalid"
          }
        ],
        "group": "fitness.orcasio.com",
        "kind": "fitnesscollators",
        "name": "buffer-cron"
      },
      "kind": "Status",
      "message": "fitnesscollators.fitness.orcasio.com \"buffer-cron\" is invalid: metadata.resourceVersion: Invalid value: 0x0: must be specified for an update",
      "metadata": {},
      "reason": "Invalid",
      "status": "Failure"
    }
  }