RelocateMetricData
The Oracle Communications Unified Assurance Relocate Metric Data tool (RelocateMetricData) is a basic threaded application for moving metric data for a single device from one zone, shard, or instance to another in the Metric database. You can also use the tool to move metric data when you change a device's name (DNSName, IPv4Address, or IPv6Address), which is mapped to the host field in the Metric database.
You can run RelocateMetricData before or after making the changes to the device in the Assure1 database.
In redundant environments, you must run the tool separately on the primary and secondary server to migrate the metrics in both databases.
RelocateMetricData uses the same timeout value as the Metric database. If you experience performance issues with the tool, you can adjust the timeout value for the Metric database using the UI. See Databases in Unified Assurance User's Guide for information about using the UI to update the timeout value.
Prerequisites
By default, Telegraf writes to the raw retention policy only. You can configure it to write to the additional hourly and daily retention policies. The application sets the rp tag to daily or hourly for data that is not in the default retention policy.
Before running RelocateMetricData, make the following additional configurations so that it can process the data written to the hourly and daily retention policies:
-
Create a new configuration file called migrate.conf in the $A1BASEDIR/etc/telegraf.d/ directory on each database server with the following content:
############################################################################### [[outputs.influxdb]] urls = ["https://<metric_host_FQDN>:8086"] database = "Metric" skip_database_creation = true retention_policy = "hourly" tagexclude = ["rp"] write_consistency = "any" timeout = "30s" tls_ca = "<UA_home>/etc/ssl/BundleCA.crt" tls_cert = "<UA_home>/etc/ssl/User-assure1.crt" tls_key = "<UA_home>/etc/ssl/User-assure1.key" [outputs.influxdb.tagpass] rp = ["hourly"] ############################################################################### [[outputs.influxdb]] urls = ["https://<metric_host_FQDN>:8086"] database = "Metric" skip_database_creation = true retention_policy = "daily" tagexclude = ["rp"] write_consistency = "any" timeout = "30s" tls_ca = "<UA_home>/etc/ssl/BundleCA.crt" tls_cert = "<UA_home>/etc/ssl/User-assure1.crt" tls_key = "<UA_home>/etc/ssl/User-assure1.key" [outputs.influxdb.tagpass] rp = ["daily"] ###############################################################################
Note:
Replace <UA_home> with the appropriate installation directory (usually /opt/assure1) and <metric_host_FQDN> with the appropriate server FQDN (for example, hostname.example.com).
-
Restart the Telegraf service:
-
Get the service ID for Telegraf:
$A1BASEDIR/bin/BrokerControl --batch listservices | grep Telegraf
-
Stop and then start Telegraf, using the returned ID:
$A1BASEDIR/bin/BrokerControl --batch stopservice <ID> $A1BASEDIR/bin/BrokerControl --batch startservice <ID>
Tip:
You can alternatively use the Services UI to restart the Telegraf service.
-
-
Run RelocateMetricData. See Administration Details for options.
Wait for the tool to finish.
-
Delete the migrate.conf configuration file.
-
Restart the Telegraf service to reverse the changes.
Administration Details
When you run RelocateMetricData, the --DeviceID option is always required. You can use the additional options to change any combination of zone, shard, DNS name, IP address, or instance name.
The following list shows the technical details needed for advanced administration of the application:
-
Package: coreProcessing-app
-
Synopsis:
./RelocateMetricData [OPTIONS]
-
Options: You can specify the options described in the following table. Actual values are in bold, descriptions of values are in plaintext. See Changing Zones or Shards and Changing DNS Names, IP Addresses, or Instance Names for more usage details and examples of the --Previous and --New options.
Concise Option Verbose Option Value Type Default Description -d --DeviceId Integer No default value. The device to move metric data for. -f --LogFile String ~/logs/RelocateMetricData.log The log file to use. -l --LogLevel Integer ALWAYS The log level to use. Options are: - 0: OFF
- 1: FATAL
- 2: ERROR
- 3: WARN
- 4: (INFO)
- 5: DEBUG
-z --NewZoneID Integer DeviceZoneID from the Assure1.Devices table. (Optional) The new ZoneID for the device. Use this option to relocate metrics when you move a device to a new zone. -p --PreviousZoneID Integer DeviceZoneID from the Assure1.Devices table (Optional) The previous ZoneID for the device. Use this option to relocate metrics when you move a device to a new zone. -s --NewShardID Integer ShardID from the Assure1.Devices table. (Optional) The new ShardID for the device. Use this option to relocate metrics when you move a device to a new shard. -n --PreviousShardID Integer ShardID from the Assure1.Devices table. (Optional) The previous ShardID for the device. Use this option to relocate metrics when you move a device to a new shard. No concise option. --NewDnsName String No default value. (Optional) The new DNS name for the device. Use this option with --PreviousDnsName to relocate metrics when you change a device's DNSName. N/A No concise option. --PreviousDnsName String No default value. (Optional) The previous DNS name for the device. Use this option with --NewDnsName to relocate metrics when you change a device's DNSName. No concise option. --NewIPAddress String No default value. (Optional) The new IPv4 address for the device. Use this option with --PreviousIPAddress to relocate metrics when you change a device's IP address. You can optionally set this to a DNS name instead of an IP address to relocate the metrics from an IP address to a DNS name. No concise option. --PreviousIPAddress String No default value. (Optional) The previous IPv4 address for the device. Use this option with --NewIPAddress to relocate metrics when you change a device's IP address. No concise option. --NewIPv6Address String No default value. (Optional) The new IPv6 address for the device. Use this option with --PreviousIPv6Address to relocate metrics when you change a device's IP address. You can optionally set this to a DNS name instead of an IP address to relocate the metrics from an IP address to a DNS name. No concise option. --PreviousIPv6Address String No default value. (Optional) The previous IPv6 address for the device. Use this option with --NewIPv6Address to relocate metrics when you change a device's IP address. No concise option. --NewInstance String No default value. (Optional) The new metric instance name for the device. Use this option with --PreviousInstance to relocate metrics when you change an instance name. No concise option. --PreviousInstance String No default value. (Optional) The previous metric instance name for the device. Use this option with --NewInstance to relocate metrics when you change an instance name. -t --Threads Integer 1 The number of threads to use. -w --FlushTime Integer 10 The number of seconds to wait to flush metrics before completing task. -r --Remove Integer 0 Whether (1) or not (0) to to remove existing data after copying the metrics. You can use this option in the same call you use to relocate data, or you can use it in a separate call, with the appropriate --Previous option only, to remove the old data after relocating it. -?, -h --Help No value No default value. (Optional) Print usage and exit. -
Threaded: Multithreaded
Changing Zones or Shards
If you run RelocateMetricData before updating the zone or shard for the device in the Assure1 database, only the --NewZoneID or --NewShardID option is required. The --PreviousZoneID or --PreviousShardID options default to what is set for the device in the Assure1.Devices table.
If you run RelocateMetricData after updating the device in the Assure1 database, only the --PreviousZoneID or --PreviousShardID option is required. The --NewZoneID or --NewShardID options default to what is set for the device in the Assure1.Devices table.
In either scenario, if you specify both new and previous options, those values are used. The tool warns you if the value of --NewZoneID or --NewShardId does not match the current value in the Assure1.Devices table, in case you mistakenly entered the wrong new value. If you have not yet made the change in the Assure1 database, you can ignore the warning.
Changing DNS Names, IP Addresses, or Instance Names
For DNS name, IP address, or instance name changes, the options for both new and previous setting are required regardless of whether you have already changed the setting in the Assure1 database. One of the settings must match what is currently in the Assure1 database. For example, --NewDnsName will match if you already renamed the device, --PreviousDnsName will match if you have not renamed it yet. If neither matches, nothing is changed in the Metric database.
If you have changed the DNS name or IP address multiple times before running RelocateMetricData, you must use the first name in the --PreviousDnsName, --PreviousIPAddress, or --PreviousIPv6Address option. The Metric database is not aware of any name changes until you run RelocateMetricData, so RelocateMetricData cannot locate the device using any of the interim names.
You can set multiple options in a single call to update all multiple settings for the same device. You can also use a single call to change the device from using IP addresses to DNS names instead.
See RelocateMetricData Examples for examples of the command with different options.
RelocateMetricData Examples
The following example commands illustrate some of the different options for relocating metrics in the Metric database:
-
To relocate metrics after changing the DNS name of device 1234 from device.example.com to device.update.example.com:
$A1BASEDIR/bin/core/processing/RelocateMetricData --DeviceID 1234 --NewDnsName "device.update.example.com" --PreviousDnsName "device.example.com"
You must specify both --NewDnsName and --PreviousDnsName, and the values must be different.
-
To relocate metrics after changing the DNS name of device 4321 multiple times, from device.example.com, to device2.example.com, to device3.example.com, and finally to device4.example.com, you set --PreviousDeviceName to device.example.com:
$A1BASEDIR/bin/core/processing/RelocateMetricData --DeviceID 4321 --NewDnsName "device4.example.com" --PreviousDnsName "device.example.com"
-
You plan to change zone 1 to zone 2 for device 1234. The value of DeviceZoneID for device 1234 in the Assure1.Devices table is currently 1.
To relocate metrics before changing the zone:
$A1BASEDIR/bin/core/processing/RelocateMetricData --DeviceID 1234 --NewZoneID 2
Because you did not specify --PreviousZoneID, the tool uses the current value of DeviceZoneID for device 1234 from the Assure1.Devices table.
It prints a warning that NewZoneID does not match Assure1.Devices.DeviceZoneID. This is expected; you have not yet changed the zone in the Assure1 database. You can safely ignore this warning.
-
You have changed shard 2 to shard 3 for device 5678. The value of ShardID for device 5678 in the Assure1.Devices table is currently 3.
To relocate metrics after changing the shard:
$A1BASEDIR/bin/core/processing/RelocateMetricData --DeviceID 5678 --PreviousShardID 2
Because you did not specify --NewShardID, the tool uses the current value of ShardID for device 5678 from the Assure1.Devices table.
-
To relocate metrics after changing a metric instance name for device 91011 from one Docker container to another:
$A1BASEDIR/bin/core/processing/RelocateMetricData --DeviceID 91011 --NewInstance "/opt/assure1/var/docker/containers/2abc/mounts/shm" --PreviousInstance "/opt/assure1/var/docker/containers/1abc/mounts/shm"
To remove the metrics from the previous metric instance after changing the name:
$A1BASEDIR/bin/core/processing/RelocateMetricData --DeviceID 91011 --PreviousInstance "/opt/assure1/var/docker/containers/1abc/mounts/shm" --Remove=1
-
To relocate metrics after changing the DNS name, IPv4 address, and IPv6 address, and remove the previous data:
$A1BASEDIR/bin/core/processing/RelocateMetricData --DeviceID 91021 --NewDnsName "new.example.com" --PreviousDnsName "old.example.com" --NewIPAddress "192.0.2.2" --PreviousIPAddress "192.0.2.1" --NewIPv6Address "2001:db8:1234:5678:9101:1121:3141:5168" --PreviousIPv6Address "2001:db8:1234:5678:9101:1121:3141:5167" --Remove=1
-
To relocate metrics from an IP address host to a DNS host:
$A1BASEDIR/bin/core/processing/RelocateMetricData --DeviceID 318 --NewIPAddress"dns.example.com" --PreviousIPAddress "192.0.2.3"
-
To relocate metrics from multiple IP address hosts to a single DNS, after changing the DNS name:
$A1BASEDIR/bin/core/processing/RelocateMetricData --DeviceID 91016 --NewDnsName "best.example.com" --PreviousDnsName "new.example.com" --NewIPAddress "best.example.com" --PreviousIPAddress "192.0.2.1" --NewIPv6Address "best.example.com" --PreviousIPv6Address "2001:db8:1234:5678:9101:1121:3141:5167"