@f5devcentral/f5-teem

f5-teem

This library is for use by Automation Toolchain products. Its purpose is to interface with F5's TEEM infrastructure to provide usage analytics to F5.

Usage

const TeemDevice = require('@f5devcentral/f5-teem').Device;
const assetInfo = {
    name: 'Declarative Onboarding',
    version: '1.2.3'
};
const teemDevice = new TeemDevice(assetInfo);
const declaration = <incoming_declaration>;
teemDevice.report('Declarative Onboarding Telemetry Data', '1', declaration);

By default, f5-teem will send a report that includes

• The type of device that on which the code is currently running (for example, 'BIG-IP')
• The TMOS software version of the device on which the code is currently running
• A count of each class type in the declaration

Note: these TEEM reports can error upon transmitting. It is best practice to catch any errors and handle them appropriatly. However, it is reasonable to discard any errors you receive, as TEEM (usually) should not prevent a project from executing. TEEM reports should not be blocking for your project, the responses are not useful.

Anonymous API Usage

In order to successfully send the information to the anonymous endpoint, an API Key will need to be provided.

Additionally, you can specify your machine id value as part of the assetInfo. This will take precedence over the automated check done if ran on a BIG-IP.

Currently, unless f5-teem is ran on a BIG-IP the product and productVersion cannot be determined and so will be labeled "unknown" in the output.

const TeemDevice = require('@f5devcentral/f5-teem').AnonymousDevice;
const assetInfo = {
    name: 'Declarative Onboarding',
    version: '1.2.3',
    id: '<ID of the machine>'
};
const teemDevice = new TeemDevice(assetInfo, <API_KEY>);
const declaration = <incoming_declaration>;
teemDevice.report('Declarative Onboarding Telemetry Data', '1', declaration);

Example rawTelemetry object sent by f5-teem

{
    "documentType": "Declarative Onboarding Telemetry Data",
    "documentVersion": "1",
    "digitalAssetId": "213d40c8-6d64-5682-b29d-bc2ac080c9e2",
    "digitalAssetName": "Declarative Onboarding",
    "digitalAssetVersion": "1.2.3",
    "observationStartTime": "2019-09-27T23:15:23.149Z",
    "observationEndTime": "2019-09-27T23:15:23.149Z",
    "epochTime": "1569626123149",
    "telemetryId": "345619b4-3e4c-429c-b15c-3ee73e3738a0",
    "telemetryRecords": [
        {
            "Device": 1,
            "Tenant": 1,
            "License": 1,
            "DNS": 1,
            "NTP": 1,
            "Provision": 1,
            "VLAN": 2,
            "SelfIp": 2,
            "platform": "BIG-IP",
            "platformVersion": "14.1.0.5"
        }
    ]
}

reportRecord API Usage

Both device and anonymousDevice have this API allowing users to specify what goes into the report, instead of using the predesigned reports. To do so, you first create and specify a record, and then the reportRecord(), will parse through it and send the information.

Here is an example of creating and sending a report using the Anonymous API.

Note: records use promises to gather the information.

const TeemDevice = require('@f5devcentral/f5-teem').AnonymousDevice;
const Record = require('@f5devcentral/f5-teem').Record;
const assetInfo = {
    name: 'Declarative Onboarding',
    version: '1.2.3',
    id: '<ID of the machine>'
};
const teemDevice = new TeemDevice(assetInfo, <API_KEY>);
const declaration = <incoming_declaration>;

const record = new Record('Declarative Onboarding Telemetry Data', '1');
return Promise.resolve()
    .then(() => record.addClassCount(declaration))
    .then(() => record.addJsonObject({ <Any JSON information you want to add> }))
    .then(() => record.addPlatformInfo())
    .then(() => teemDevice.reportRecord(record));

Record functions

Can be used anywhere

• addClassCount(declaration) - Accepts and parses the declaration, adding the number of classes it finds. Can be called multiple times, incrementing the number of found classes.
• addJsonObject(jsonObject) - Accepts a JSON object and adds it directly to the record.

Must be ran on a BIG-IP

• addPlatformInfo() - Pulls the platform information from localhost and parses it into the record.
• addRegKey() - Pulls the RegKey information from localhost and adds it to the record.
• addProvisionedModules() - Pulls and parses the available and provisioned modules and adds the provisioning level of each module to the record.
• calculateAssetId() - Pulls the machineId and creates a hash, this will be used if no assetInfo.id is provided.

Advanced usage

Disable f5-teem from sending data

f5-teem honors the phone home setting. To disable f5-teem from sending data:

tmsh modify sys software update auto-phonehome disabled

Send custom Data

To send more than the default data, send extra records to the report API

const extraFields = {
    status: 'OK',
    firstRun: false
};
teemDevice.report('Declarative Onboarding Telemetry Data', '1', declaration, extraFields);

Use TEEM staging environment

• edit the file /service/restnoded/run
  • before the lines that start restnoded, add the line:

  export TEEM_API_ENVIRONMENT='staging'

• bigstart restart restnoded