Upgrading TrackMe

1. Introduction

Upgrading TrackMe is a straightforward process which is similar to the installation.

However, TrackMe as well implements a sophisticated and automated upgrade process called schema version which is used to dynamically run specific action depending on the origin versoon and the state of TrackMe Virtual tenants.

The action can imply the deletion, creation or update of TrackMe knowledge objects depending on the context.

The purpose of this documentation is to deeply describe how the schema version upgrade works.

2. Schema version

Once you have upgraded TrackMe using the Splunk standard upgrade process depending on your context (Splunk Enterprise versus Cloud, SHC versus standalone), TrackMe will automatically verify and perform additional upgrade procedures as needed.

The schema version is versioning information which is stored in the KVstore record of the Virtual Tenant, you can verify the current schema version value in the central KVstore:

| inputlookup trackme_virtual_tenants | eval keyid=_key
| fields keyid, tenant_id, schema_version
screen1.png

The schema version corresponds to the TrackMe version minus the “dots”, if you are running versio 2.0.20, the schema version is 2020.

2.1 Schema version verification

The schema version verification is an automated process handled by the Health tracker of the Virtual Tenant.

When a Virtual Tenant is created, TrackMe also creates a dedicated Health tracker for this tenant, the Health tracker is responsible for various administration tasks such as detecting any issues encountered by the tenant’s trackers, as well as running the schema version verification.

Health tracker name in Splunk:

  • trackme_health_tracker_tenant_<tenant_id>

2.2 Logs

The logs of the Health tracker and any upgrade related events are available via the navigation bar shortcut “Audit & Troubleshoot / Logs - TrackMe custom commands / common to components / trackmetrackerhealth” and match the following index/sourcetype:

index=_internal sourcetype=trackme:custom_commands:trackmetrackerhealth context="schema_upgrade"

2.3 Schema version upgrade & traces

When the Health Tracker runs (every 5 minutes), it verifies the schema version:

2023-04-17 21:38:18,464 INFO trackmetrackerhealth.py generate 207 tenant_id="feeds-tracking", context="schema_upgrade", current schema_version="2020"

If an upgrade is required, the following message is logged:

2023-04-17 13:56:18,930 INFO trackmetrackerhealth.py generate 251 tenant_id="feeds-tracking", context="schema_upgrade", detected migration required for schema version 2020, processing now.

Required procedures are then performed automatically, these depend on the originating version, for instance:

2023-04-17 13:56:18,960 INFO trackme_libs.py trackme_create_report 314 tenant_id="feeds-tracking", context="schema_upgrade", attempting to create report report_name="trackme_dsm_delayed_entities_tracker_tenant_feeds-tracking"
2023-04-17 13:56:18,999 INFO trackme_libs.py trackme_create_report 331 tenant_id="feeds-tracking", context="schema_upgrade", action="success", report_name="trackme_dsm_delayed_entities_tracker_tenant_feeds-tracking"

Once, all required upgrade operations have been achieved, the following message is logged:

2023-04-17 13:56:19,267 INFO trackmetrackerhealth.py generate 254 tenant_id="feeds-tracking", context="schema_upgrade", schema version 2020 migrated successfully, results="{
"object": "trackme_dhm_delayed_entities_tracker_tenant_feeds-tracking",
"object_type": "report",
"action": "create",
"result": "success"
}"

Disabled Virtual Tenants

  • Disabled Virtual Tenants are not migrated as long as these are disabled (since the Health Tracker will not run)

  • If the Virtual Tenant is re-enabled, its upgrade will be processed automatically within the next 5 minutes