Nuns Practicing Misanthropy

    @f5devcentral/f5-teem

    1.5.0 • Public • Published

    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('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

    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('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('f5-teem').AnonymousDevice;
    const Record = require('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

    Keywords

    none

    Install

    npm i @f5devcentral/f5-teem

    DownloadsWeekly Downloads

    2,806

    Version

    1.5.0

    License

    Apache-2.0

    Unpacked Size

    76.5 kB

    Total Files

    22

    Last publish

    Collaborators

    • dstokesf5
    • dumpysquare
    • seattlevine
    • citizenelah
    • garrettdieckmann
    • sschadwick
    • jsevedge
    • andrey.kashcheev
    • gcrosby
    • a.smithf5
    • mikeshimkus
    • mstokes-f5
    • nitinkhanna
    • hvaneenoo
    • elliotwilcock