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 theconfigurationfile, 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
- 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:
|
|
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. |
|
telemetry.chargeBackId | Your department's non-personally identifiable information (non-PII) identifier that you use for your company's tracking needs. |
|
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 |
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 milliseconds2019-04-05T15:41:46.533-0700 INFO 1 com.l7tech.server: Internal Audit System started2019-04-05T15:41:46.560-0700 INFO 1com.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 1com.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.