Telemetry Data

Telemetry is a capability that is integrated to collect and send the product usage and system configuration information of the Mobile API Gateway environment to CA Technologies, a Broadcom company (CA).
gateway10cr2
2
The information on this page, including configuration steps, applies only to customers who have signed a Portfolio License Agreement (PLA) with Layer7, a Broadcom company.

Overview

Telemetry is a capability that is integrated to collect and send the product usage and system configuration information of the
Layer7 API Gateway
environment to Broadcom Layer7. This data helps Layer7 gain insights into customers' product usage, understand their software needs, and focus on the features and platforms that are most commonly used.
PLA Customers
When configuring the Gateway with a PLA, you must identify your instance as a PLA instance during setup, allow collected data to be sent AND use a method of sending telemetry data. You must also provide activation information that includes your company domain and enterprise site ID.
Non-PLA Customers
As a non-PLA customer, you are not required to perform any actions for telemetry configuration. However, if you wish to inform Broadcom Layer7 how your organization is using the Gateway, you may still opt to send telemetry data by setting the Segment enablement property to 'true'.

What Data is Being Collected?

The collected information comprises of two types of telemetry data:
  • Data that is provided by customers in the
    configuration
    file, including:
    • Whether the installation or upgrade is a new or additional planned usage under a PLA
    • Your company's domain name
    • Your company's enterprise site ID
    • Your cost center's internal identifier
  • Data that is automatically generated by
    Layer7 API Gateway
    , including:
    • Gateway usage, measured according to the uptime
      (in minutes) that is recorded during the monitored period – each period begins with Gateway startup and ends with Gateway shutdown or restart
    • Operating System
    • Linux distribution (e.g., RHEL, Centos, Others)
    • Product SKU (e.g., APIENT990)  and description (e.g., Layer7 API Gateway Enterprise)
    • Product version (e.g., Gateway 9.4.00 build 9332)
    • Gateway node identifier
Telemetry does not transmit any Personally Identifiable Information (PII). Broadcom Layer7 continues to follow the policy as outlined in our privacy statement:  https://www.broadcom.com/company/legal/privacy/policy

Methods and Frequency of Data Collection

The following telemetry reporting options are available to PLA customers:
  • Use the default telemetry reporting option, which automatically sends telemetry data to Broadcom. Collected data is sent to Broadcom every 24 hours. Make sure to open your firewall for
    If your installation of Gateway cannot directly send outbound requests to , you can set up a proxy to connect to Broadcom. The proxy server must be defined using a URL format, for example:
    https://theproxy.com:3129
    or
    http://theproxy.com:3128
    .
    The Gateway allows proxy servers to support both HTTP and HTTPS with or without credentials (Basic Authentication).
  • Manually extract telemetry logs and report them to Broadcom, as per the frequency and conditions provided in your PLA.

Appliance or Software Gateway: Configure Telemetry with the Telemetry Properties File

As an administrator, provide the following parameters in the
/opt/SecureSpan/Gateway/node/default/etc/conf/telemetry.properties
file after installing the Gateway.  If you modify the
telemetry.properties
file, restart the Gateway to apply the new configuration.
Parameter
Notes
Example
telemetry.pla.enabled
Indicates whether the installation of the Gateway is part of a PLA. Default Value:
false
If you are a PLA customer, enter a value of
true
. If you are a non-PLA customer, leave the value of
false
as is.
true
telemetry.segment.enabled
Indicates whether collected telemetry data is sent to Broadcom. Default value:
false
If you want the Gateway to automatically send telemetry data to Broadcom, enter a value of
true
.
If you are manually sending telemetry data to CA, leave the value of
false
as is.
true
telemetry.usageType
Indicates usage type:
production
,
nonproduction,
or
workstation
. Default value:
production
Each unique Gateway usage type is represented by a product SKU. They are summarized as follows:
  • Production
    : Handles actual traffic for your APIs.
  • Non-production
    : Used to configure policy development, testing, and staging environments.
  • Workstation
    : Typically installed on a desktop machine and used strictly for policy development purposes.
production
telemetry.domainName
The domain name of your company. It is the last part of your company's email address.
xyz.com
telemetry.siteId
Your company's 4- to 9-digit unique login site ID that is listed on your PLA and the Support portal.
10986
telemetry.chargeBackId
Your department's non-personally identifiable information (non-PII) identifier that you use for your company's tracking needs.
IT-Sales-1234
telemetry.segment.endpoint
REQUIRED. Broadcom URL of the destination for sent telemetry data. If you are unable to find the parameter in the properties file, you'll need to manually enter both the parameter and value in the properties file.
https://telemetry.broadcom.com/loaddata
Optional
telemetry.proxy.url
The URL, including protocol and port, of your proxy server.
https://myproxy.net:3610
telemetry.proxy.username
The user name of your proxy authentication.
telemetry.proxy.password
The plain-text password that is associated with the proxy URL user name.
Telemetry.properties Sample
# # Configuration properties for Telemetry under the Enterprise Software Portfolio License Agreement (PLA) # For additional information about how information is collected and used, please refer to our privacy statement # https://www.broadcom.com/company/legal/privacy-policy # This install or upgrade is related to new or additional planned usage under a Portfolio License Agreement telemetry.pla.enabled=true # Determine whether collected telemetry data shall be sent to Broadcom. Enter a value of false to prevent data from being sent (opt-out) to Broadcom. telemetry.segment.enabled=true # REQUIRED: Define the Broadcom URL or site that telemetry data will be sent to telemetry.segment.endpoint=https://telemetry.broadcom.com/loaddata # Type of usage. Should be one of: production, nonproduction, workstation telemetry.usageType=production # Enter values if usage is under a PLA (these should be left blank otherwise): # Company Domain - Enter the last part of your company's email address telemetry.domainName= # Enterprise Site ID - Listed on your agreement and the Support Portal telemetry.siteId= # Optional Internal Identifier (charge back id) Ex: A department or cost center - that you use for internal tracking telemetry.chargebackId= # Optional Proxy Configuration # Proxy URI https://myproxy.company.com telemetry.proxy.url= telemetry.proxy.username= telemetry.proxy.password=

Manually Sending Telemetry Data

If your organization cannot allow the Gateway to automatically send telemetry information to Broadcom (with or without a proxy), then you are required to manually send telemetry data as per PLA requirements.
How you extract the logs will be entirely up to you - you may copy and paste the log entries from the .log file onto a text file or you may create a new log file via the Policy Manager with a telemetry log filter if you have a large volume of system logs to review.
Any log entry associated with telemetry will be flagged with the
com.l7tech.server.telemetry.GatewaySegmentService
package name – you may use this name to filter your logs in Policy Manager.
The following snippet shows two sample log entries with the telemetry package name in a .log file.
2019-04-05T15:41:46.532-0700 INFO 1 com.l7tech.server.jdbc.JdbcQueryingManagerImpl: JDBC cache clean up task starting with refresh interval of 60000 milliseconds
2019-04-05T15:41:46.533-0700 INFO 1 com.l7tech.server: Internal Audit System started
2019-04-05T15:41:46.560-0700 INFO 1
com.l7tech.server.telemetry.GatewaySegmentService
: Telemetry message to be sent [IdentifyMessage{type=identify, messageId=730a4162-50ba-4151-a7a7-8934326d1270, timestamp=Fri Apr 05 15:41:46 PDT 2019, context=null, anonymousId=24a56422-5cfa-4e7f-b184-72c771c528df, userId=null, integrations={}, traits={pla_enabled=0, product_sku=APIENT990, domain_name=, instance_id=48b5a4bc60fd4db191ddd5258eab0a35, site_id=, sku_description=Layer7 API Gateway Enterprise, chargeback_id=}}]
2019-04-05T15:41:46.563-0700 INFO 1
com.l7tech.server.telemetry.GatewaySegmentService
: Segment service is disabled. Telemetry message to be sent [IdentifyMessage{type=identify, messageId=730a4162-50ba-4151-a7a7-8934326d1270, timestamp=Fri Apr 05 15:41:46 PDT 2019, context=null, anonymousId=24a56422-5cfa-4e7f-b184-72c771c528df, userId=null, integrations={}, traits={pla_enabled=0, product_sku=APIENT990, domain_name=, instance_id=48b5a4bc60fd4db191ddd5258eab0a35, site_id=, sku_description=Layer7 API Gateway Enterprise, chargeback_id=}}]
The minimum logging level required for this package to appear is INFO.
After collecting your telemetry logs, please follow the instructions outlined in your PLA agreement on how to send your telemetry information.
Appliance/Software Gateway Form Factor
There are several methods to view logs for the Appliance or Software Gateway - for a refresher on those methods, see View Logs for the Gateway.
If you are viewing logs in the Gateway file structure, telemetry logs will appear in the same default location as Gateway logs:
/opt/SecureSpan/Gateway/node/default/var/logs/ssg*