Product Licensing and Telemetry

2
gateway94
2
The information on this page, including configuration steps, applies only to customers who have signed a Portfolio License Agreement (PLA) with CA Technologies, a Broadcom company (CA).
Overview
Telemetry is a capability that is integrated to collect and send the product usage and system configuration information of the CA API Gateway environment to CA Technologies. This data helps CA 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 CA Technologies how your organization is using the Gateway, you may still opt to send telemetry data by setting the Segment enablement property to 'true'. 
The configuration file and actual property names used for enablement will depend on whether you're using the Appliance/Software or Docker container form factors of the gateway. 
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 CA 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)
    • Whether or not the Gateway is running in the Docker container form factor
    • Product SKU (e.g., APIENT990)  and description (e.g., CA 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). CA Technologies continues to follow the policy as outlined in our privacy statement:  https://www.ca.com/us/legal/privacy.html
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 Segment. Collected data is sent to Segment every 24 hours. Make sure to open your firewall for https://api.segment.io
    If your installation of Gateway cannot directly send outbound requests to https://api.segment.io, you can set up a proxy to connect to Segment. 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 CA, 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 Segment. Default value:
false
If you want the Gateway to automatically send telemetry data to Segment, 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.
telemetry.siteId
Your company's 4- to 9-digit unique login site ID that is listed on your PLA and the CA 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
Optional
telemetry.proxy.url
The URL, including protocol and port, of your proxy server.
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.ca.com/us/legal/privacy.html # # 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 Segment.io. Enter a value of false to prevent data from being sent (opt-out) to Segment.io telemetry.segment.enabled=true # 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 CA 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=
Docker Container Gateway: Configure Telemetry with Environmental Variables
The telemetry configurations for Container Gateways (Docker) are done via environment variables in the docker-compose.yml file. 
Environment Variable
Notes
Example
TELEMETRY_PLA_ENABLE
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_ENABLE
Indicates whether collected telemetry data is sent to Segment. Default value:
false
If you want the Gateway to automatically send telemetry data to Segment, enter a value of
true
.
If you are manually sending telemetry data to CA, leave the value of
false
as is.
true
TELEMETRY_USAGE_TYPE
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_DOMAIN_NAME
The domain name of your company. It is the last part of your company's email address.
xyz.com
TELEMETRY_SITE_ID
Your company's 4- to 9-digit unique login site ID that is listed on your PLA and the CA Support portal.
10986
TELEMETRY_CHARGEBACK_ID
Your department's non-personally identifiable information (non-PII) identifier that you use for your company's tracking needs.
IT-Sales-1234
Optional
TELEMETRY_PROXY_URL
The URL, including protocol and port, of your proxy server.
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.
Docker-compose.yml Sample 
version: 'X.X' services: api-gateway: image: caapim/gateway # cpus: 4 # mem_limit: 6g # memswap_limit: 6g # mem_swappiness: 0 ports: - "8080" - "8443" - "9443" # volumes: # - /opt/SecureSpan/Gateway/node/default/etc/bootstrap/services/restman environment: ACCEPT_LICENSE: "false" # SSG_ADMIN_USERNAME: "adminUser" # SSG_ADMIN_PASSWORD: "somepassword" # SSG_DATABASE_JDBC_URL: "jdbc:mysql://mysql-server:3306/ssg" # SSG_DATABASE_USER: "ssgdbuser" # SSG_DATABASE_PASSWORD: "dbpassword" # SSG_CLUSTER_HOST: "mycompany.host.com" # SSG_CLUSTER_PASSWORD: "clusterpassword" # SSG_JVM_HEAP: "4g" # EXTRA_JAVA_ARGS: "-XX:ParallelGCThreads=4 -Dcom.l7tech.bootstrap.autoTrustSslKey=trustAnchor,TrustedFor.SSL,TrustedFor.SAML_ISSUER" # 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.ca.com/us/legal/privacy.html TELEMETRY_SEGMENT_ENABLE: "true" TELEMETRY_PLA_ENABLE: "true" TELEMETRY_SITE_ID: "12345" TELEMETRY_USAGE_TYPE: "nonproduction" TELEMETRY_DOMAIN_NAME: "broadcom.com" TELEMETRY_CHARGEBACK_ID: "APIM" # TELEMETRY_PROXY_URL: "https://theproxy.com:3129" # TELEMETRY_PROXY_USERNAME: "proxyUser" # TELEMETRY_PROXY_PASSWORD: "proxypassword"
Manually Sending Telemetry Data 
If your organization cannot allow the Gateway to automatically send telemetry information to Segment (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=CA 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=CA 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*
Docker Container Gateway Form Factor
Docker Container Gateways write logs to the console only - to learn how to access these logs, see Logs for the Container Gateway in Docker