UIM communicates with the Topology Service using REST APIs and Kafka Message Bus. UIM is the Producer for Create, Update and Delete operations from UIM that impact Topology. UIM uses REST APIs to communicate directly with the ATA Service while building the messages and can also continue processing when the Topology Service is unavailable.

The ATA consumer service is a message consumer for topology updates from UIM using Message Bus service. ATA consumer processes the message of TopologyNodeCreate, TopologyNodeUpdate, TopologyNodeDelete, TopologyEdgeCreate, TopologyEdgeUpdate, TopologyEdgeDelete, TopologyProfileDelete, TopologyProfileDelete, and TopologyProfileUpdate event types. See "ATA Events and Definitions" chapter in Active Topology and Automator Asynchronous Events Guide.

The ATA alarm consumer service consumes TMF642 wrapped in TMF688 messages from the Assurance systems. The alarm consumer supports processing of multiple messages of event types AlarmCreateEvent, AlarmAttributeValueChangeEvent, ClearAlarmCreateEvent, and AlarmDeleteEvent. In incoming alarm messaged from the Assurance system can be of two types, normal alarm (fault) and threshold crossing (performance) alarm. The alarm consumer will extract the alarmed object identifier from the input message and creates and associates the event (alarm) to the inventory resource.

SmartSearch API enables you to search, filter, autocompletes, or aggregates the bulk API to batch process for insert, update, or delete top entries from the OpenSearch database.

SmartSearch is a consumer for UIM. It processes multiple message events such as TopologyNodeCreate, TopologyNodeUpdate, TopologyNodeDelete, TopologyEdgeCreate, TopologyEdgeUpdate, TopologyEdgeDelete and so on.

OpenSearch is NoSQL database it is an open-source search and analytics suite that makes it easy to ingest, search, visualize, and analyze data.

The ATA Service communicates to the Oracle Databases using the Oracle Property Graph feature with PGQL and standard SQL. It can communicate directly to the database or with the In-Memory Graph for high performance operations. This converged database feature of Oracle Database makes it possible to utilize the optimal processing method with a single database. The Graph Database is isolated and a separate Pluggable Database (PDB) from the UIM Database but runs on the same 19c version for simplified licensing.

The ATA Service also uses the Oracle Labs Parallel Graph AnalytiX (PGX) In-Memory database. The PGX server is used for Path Analysis and is configured for periodic updates.

ATA provides a graphical representation of topology where you can see your inventory and its relationships at the level of detail that meets your needs. ATA is built using Oracle Redwood Design System.

You require the following prerequisites for creating ATA images:

• Podman on the build machine if Linux version is greater than or equal to 8.
• Docker on the build machine if Linux version is lesser than 8
• ATA Builder Toolkit (ref about the deliverables)
• Install Maven and update path variable with Maven Home.

  Set PATH variable export PATH=$PATH:$MAVEN_HOME/bin

• Java, installed with JAVA_HOME set in the environment.

  Set PATH variable export PATH=$PATH:$JAVA_HOME/bin

• Bash, to enable the `<tab>` command complete feature.

See "UIM Software Compatibility" in UIM Compatibility Matrix for details about the required and supported versions of these prerequisite software.

The dependency manifest file describes the input that goes into the ATA images. It is consumed by the image build process. The default configuration in the latest manifest file provides the necessary components for creating the ATA images easily. See "About the Manifest File" for more information.

The ATA image builder creates images with names and tags based on the settings in the manifest file. By default, this results in the following images:

• uim-7.7.0.0.0-ata-base-1.2.0.0.0:latest
• uim-7.7.0.0.0-ata-api-1.2.0.0.0:latest
• uim-7.7.0.0.0-ata-pgx-1.2.0.0.0:latest
• uim-7.7.0.0.0-ata-ui-1.2.0.0.0:latest
• uim-7.7.0.0.0-ata-dbinstaller-1.2.0.0.0:latest
• uim-7.7.0.0.0-ata-consumer-1.2.0.0.0:latest
• uim-7.7.0.0.0-alarm-consumer-1.2.0.0.0:latest
• uim-7.7.0.0.0-smartsearch-consumer-1.2.0.0.0:latest
• uim-7.7.0.0.0-impact-analysis-api-1.2.0.0.0:latest

The specification names in the ATA application can be localized. To achieve this, export the specification bundle from UIM and build the image with customization.

The prerequisite for localizing specification name in ATA is that the specification displays names provided in Service Catalog and Design - Design Studio and deployed to UIM.

To localize the specification name:

1. Export UIM App Bundle:
   1. In UIM UI, navigate to Execute Rule under Administration section in the left pane.
   2. Select EXPORT_SPECIFICATION_DISPLAY_NAMES_AS_JSON from the dropdown, ignore the file upload option, and click Process.

      Note:

      The ora_uim_baserulesets must be deployed before performing this step.
   3. Download uimAppBundle.tar.gz.
2. Place uimAppBundle.tar.gz in $BUILDER_HOME/staging/downloads/ata-ui/uimAppBundle builder for image building.
3. Customize and build the image.

Build container images for the following using the ATA cloud native Image Builder:

• ATA Core application
• ATA PGX application
• ATA Consumer application
• Alarm Consumer application
• ATA User Interface application
• ATA database installer
• SmartSearch Consumer application

See "Deployment Toolkits" to download the Common cloud native toolkit archive file. Set the variable for the installation directory by running the following command, where $WORKSPACEDIR is the installation directory of the COMMON cloud native toolkit:

export COMMON_CNTK=$WORKSPACEDIR/common-cntk

ATA relies on access to certain environment variables to run seamlessly. Ensure the following variables are set in your environment:

• Path to your common cloud native toolkit
• Traefik namespace
• Path to your specification files

To set the environment variables:

1. Set the COMMON_CNTK variable to the path of directory where common cloud native toolkit is extracted as follows:

   $ export COMMON_CNTK=$WORKSPACEDIR/common-cntk

2. Set the TRAEFIK_NS variable for Traefik namespace as follows:

   $ export TRAEFIK_NS=Treafik Namespace

3. Set the TRAEFIK_CHART_VERSION variable for Traefik helm chart version. Refer UIM Compatibility Matrix for appropriate version. The following is a sample for Traefik chart version 15.1.0.

   $ export TRAEFIK_CHART_VERSION=15.1.0

4. Set SPEC_PATH variable to the location where application and database yamls are copied. See "Assembling the Specifications" to copy specification files if not already copied.

   $ export SPEC_PATH=$WORKSPACEDIR/ata_spec_dir

After you set the environment variables, register the namespace.

To register the namespace, run the following command:

$COMMON_CNTK/scripts/register-namespace.sh -p sr -t targets
# For example, $COMMON_CNTK/scripts/register-namespace.sh -p sr -t traefik
# Where the targets are separated by a comma without extra spaces

You must store sensitive data and credential information in the form of Kubernetes Secrets that the scripts and Helm charts in the toolkit consume. Managing secrets is out of the scope of the toolkit and must be implemented while adhering to your organization's corporate policies. Additionally, ATA service does not establish password policies.

As a prerequisite to use the toolkit for either installing the ATA database or creating a ATA instance, you must create secrets to access the following:

• ATA Database
• UIM Instance Credentials
• Common oauthConfig Secret for authentication

The toolkit provides sample scripts to perform this. These scripts should be used for manual and faster creation of an instance. It does not support any automated process for creating instances. The scripts also illustrate both the naming of the secret and the layout of the data within the secret that ATA requires. You must create secrets before running the install-database.sh or create-applications.sh scripts.

To install the ATA schema:

1. Update values under ata-dbinstaller in $SPEC_PATH/sr/quick/database.yaml file with values required for ATA schema creation.

   Note:

   • The YAML formatting is case-sensitive. Use a YAML editor to ensure that you do not make any syntax errors while editing. Follow the indentation guidelines for YAML.
   • Before changing the default values provided in the specification file, verify that they align with the values used during PDB creation. For example, the default tablespace name should match the value used when PDB is created.
2. Edit the database.yaml file and update the DB installer image to point to the location of your image as follows:

   ata-dbinstaller:
     dbinstaller:
       image:  DB_installer_image_in_your_repo
       tag: DB_installer image tag in your repo
   

3. If your environment requires a password to download the container images from your repository, create a Kubernetes secret with the Docker pull credentials. See "Kubernetes documentation" for details. Refer the secret name in the database.yaml. Provide image pull secret and image pull policy details.

   ata-dbinstaller:
     imagePullPolicy: Never
   # The image pull access credentials for the "docker login" into Docker repository, as a Kubernetes secret.
   # Uncomment and set if required.
   #  imagePullSecret: ""
   

4. Run the following script to start the ATA DB installer, which instantiates a Kubernetes pod resource. The pod resource lives until the DB installation operation completes.

   $COMMON_CNTK/scripts/install-database.sh -p sr -i quick -f $SPEC_PATH/sr/quick/database.yaml -a ata -c 1

5. You can run the script with -h to see the available options.
6. Check the console to see if the DB installer is installed successfully.
7. If the installation has failed, run the following command to review the error message in the log:

   kubectl logs -n sr sr-quick-ata-dbinstaller

8. Clear the failed pod by running the following command:

   helm uninstall sr-quick-ata-dbinstaller -n sr

9. Run the install-database script again to install the ATA DB installer.

The applications.yaml file is a Helm override values file to override default values of ATA chart. Update values under chart ata in $SPEC_PATH/<PROJECT>/<INSTANCE>/applications.yaml to override the default values.

The applications.yaml provides a section for values that are common for all microservices. Provide Values under that common section and it is reflected for all services.

To configure the project specification:

1. Edit the applications.yaml to provide the image in your repository (name and tag) by running the following command:

   vi $SPEC_PATH/$PROJECT/$INSTANCE/applications.yaml
   
   # edit the image names, to reflect the ATA image names and location in your docker repository
   # edit the image tags to reflect the ATA image names and location in your docker repository
   
   ata:
     name: "ata"
     image:
       topologyApiName: uim-7.7.0.0.0-ata-api-1.2.0.0.0
       pgxName: uim-7.7.0.0.0-ata-pgx-1.2.0.0.0
       uiName: uim-7.7.0.0.0-ata-ui-1.2.0.0.0
       topologyConsumerName: uim-7.7.0.0.0-ata-consumer-1.2.0.0.0
       smartsearchConsumerName: uim-7.7.0.0.0-smartsearch-consumer-1.2.0.0.0
       alarmConsumerName: uim-7.7.0.0.0-alarm-consumer-1.2.0.0.0
       impactAnalysisApiName: uim-7.7.0.0.0-impact-analysis-api-1.2.0.0.0
       topologyApiTag: latest
       pgxTag: latest
       uiTag: latest
       topologyConsumerTag: latest
       smartsearchConsumerTag: latest
       alarmConsumerTag: latest
       impactAnalysisApiTag: latest
       repository: 
       repositoryPath:

2. If your environment requires a password to download the container images from your repository, create a Kubernetes secret with the Docker pull credentials. See the "Kubernetes documentation" for details. See the secret name in the applications.yaml for more information.

   # The image pull access credentials for the "docker login" into Docker repository, as a Kubernetes secret.
   # uncomment and set if required.
    
   ata:
   #  imagePullSecret:
   #    imagePullSecrets:
   #      - name: regcred
   

3. Set Pull Policy for ATA images in applications.yaml. Set pullPolicy to Always in case image is updated.

   ata:
     image:
       pullPolicy: Never
   

4. Update loadbalancerport in applications.yaml. If there is no external loadbalancer configured for the instance change the value of loadbalancerport to the ingressController NodePort . If SSL is enabled on ATA, provide SSL NodePort and if SSL is disabled, provide non-SSL NodePort.

   If you use Oracle Cloud Infrastructure LBaaS, or any other external load balancer, if TLS is enabled set loadbalancerport to 443 else set loadbalancerport to 80 and update the value for loadbalancerhost appropriately.

   #provide loadbalancer port
   loadbalancerport: 30305

5. To enable authentication, set the flag authentication.enabled to true. If OAM is used for authentication, provide loadbalancer ip-address and ohs-hostname under hostAliases. The hostAliases are added under the pods within the /etc/hosts file. If you use any other IDP and it is not under the public dns server, you can provide the hostAliases.

   # The enabled flag is to enable or disable authentication
   authentication:
     enabled: true
    
   hostAliases:
   - ip: <ip-address>
     hostnames:
     - <oam-instance>.<oam-project>.ohs.<hostSuffix> (ex quick.sr.ohs.uim.org)

6. If Authentication is not enabled on ATA and want to integrate ATA with traditonal SSL enabled UIM, you have to create inventorySSL secret and enable the inventorySSL flag in applications.yaml as shown below:

   # make it true if using on prem inventory with ssl port enabled and authentication is not enabled on topology
   # always false for Cloud Native inventory
   # not required in production environment
   isInventorySSL: true

Sample configuration files topology-static-config.yaml.sample, topology-dynamic-config.yaml.sample are provided as the sample files for ATA API service that are under $COMMON_CNTK/charts/ata-app/charts/ata/config/ata-api

To override configuration properties, copy the sample static property file to topology-static-config.yaml and sample dynamic property file to topology-dynamic-config.yaml. Provide key value to override the default value provided out-of-the-box for any specific system configuration property. The properties defined in property files are fed into the container using Kubernetes configuration maps. Any changes to these properties require the instance to be upgraded. Pods are restarted after configuration changes to topology-static-config.yaml.

The sample configuration files topology-static-config.yaml.sample and topology-dynamic-config.yaml.sample are provided under $COMMON_CNTK/charts/ata-app/charts/ata/config/ata-api.

To override configuration properties, copy the sample static property file to topology-static-config.yaml and sample dynamic property file to topology-dynamic-config.yaml. Provide key value to override the default value provided out-of-the-box for any specific system configuration property. The properties defined in property files are provided to the container using Kubernetes configuration maps. Any changes to these properties require the instance to be upgraded. Pods are restarted after configuration changes to topology-static-eexconfig.yaml.

mp.messaging:
      incoming:
        toInventoryChannel:
    #      max.poll.interval.ms: 300000
    #      max.poll.records: 500
        toFaultChannel:
    #      max.poll.interval.ms: 300000
    #      max.poll.records: 500
        toRetryChannel:
    #      max.poll.interval.ms: 300000
    #      max.poll.records: 200
        toDltChannel:
    #      max.poll.interval.ms: 300000
    #      max.poll.records: 100

mp.messaging
  connector:
    helidon-kafka:
      partition.assignment.strategy: org.apache.kafka.clients.consumer.CooperativeStickyAssignor

Sample configuration files alarm-consumer-static-config.yaml.sample and alarm-consumer-dynamic-config.yaml.sample are provided under $COMMON_CNTK/charts/ata-app/charts/ata/config/alarm-consumer.

To override configuration properties, copy the sample static property file to alarm-consumer-static-config.yaml and sample dynamic property file to alarm-consumer-dynamic-config.yaml. Provide key value to override the default value provided out-of-the-box for any specific system configuration property. The properties defined in property files are provided to the container using Kubernetes configuration maps. Any changes to these properties require the instance to be upgraded. Pods are restarted after configuration changes to alarm-consumer-static-config.yaml.

impactAnalysis:
  url: http://localhost:8084

"alarmedObject": {
        "@referredType": "OT_AID",
        "@type": "AlarmedObjectRef",
        "id": "LSN/EMS_XDM_33/9489:73:12295",
        "name": ""
}

deviceMapping:
  inventory:
    lookupFields: # ordered ascending, only four values supported [name,id,deviceIdentifier,ipv4,ipv6]
    - name #default
    - id
    - deviceIdentifier
    - ipv4
    - ipv6
  customizeDeviceLookup:
    enabled: true

import groovy.json.JsonSlurper
 
def getDeviceIds(alarmedObject,alarm){
    def jsonSlurper = new JsonSlurper()
    def alo = jsonSlurper.parseText(alarmedObject)
    def aloId = alo.id
    def device = aloId.split(":")[0].trim()
    /*
    * The return type must be type of String.
    * The string value will be used to search in database which expected to be matched with a device/ subdevice.
    */
    return device
}

To integrate ATA API service with Message Bus service:

1. In the file $SPEC_PATH/sr/quick/applications.yaml, uncomment the section messagingBusConfig.
2. Provide namespace and instance name on which the Messaging Bus service is deployed.
3. Security protocol is SASL_PLAINTEXT if authentication is enabled on Message bus service. If authentication is not enabled on the Message Bus service, the security protocol is PLAINTEXT.

A sample configuration when authentication is enabled and Messaging Bus is deployed on instance 'quick' and namespace 'sr' is as follows:

applications.yaml

authentication:
  enabled: true 

messagingBusConfig:
  namespace: sr
  instance: quick

If Authorization Service is installed, you can integrate ATA with Authorization service by updating $SPEC_PATH/project/instance/applications.yaml and uncommenting the following properties and provide appropriate values:

authorizationServiceConfig:
  namespace: <project> #namespace on which authorization service is deployed
  instance: <instance> #instance name on which authorization service is deployed

To create an ATA instance in your environment using the scripts that are provided with the toolkit:

1. Run the following command to create an ATA instance:

   $COMMON_CNTK/scripts/create-applications.sh -p sr -i quick -f $SPEC_PATH/sr/quick/applications.yaml -a ata

   The create-applications script uses the helm chart located in $COMMON_CNTK/charts/ata-app to create and deploy a ata service.

2. If the scripts fail, see the Troubleshooting Issues section at the end of this topic, before you make additional attempts.

For more information on creating an ATA instance, see "Creating an ATA Instance"

To validate the ATA instance:

1. Run the following to check the status of ata instance deployed.

   $COMMON_CNTK/scripts/application-status.sh -p sr -i quick -f $SPEC_PATH/sr/quick/applications.yaml -a ata

   The application-status script returns the status of ATA service deployments and pods status.

2. Run the following endpoint to monitor health of ata:

   https://quick.sr.topology.uim.org:<loadbalancerport>/health

3. Run the following ATA service endpoints to add entry in /etc/hosts <k8s cluster ip or external loadbalancer ip> quick.sr.topology.uim.org:
   • ATA UI endpoint: https://quick.sr.topology.uim.org:30443/apps/ata-ui
   • ATA API endpoint: https://quick.sr.topology.uim.org:30443/topology/v2/vertex

Once the instance is created succesfully, cronjob needs to schedule for ata-pgx pod restarts. For a scheduled period of time, one of the ata-pgx pod is restarted and all incoming requests are routed to other unfified-topology-pgx pod seamlessly.

Update the script $COMMON_CNTK/samples/cronjob-scripts/pgx-restart.sh to include required environment variables - KUBECONFIG, pgx_ns, pgx_instance. For a basic instance, pgx_ns is sr and pgx_instance is quick.

export KUBECONFIG=<kube config path>
export pgx_ns=<ata project name>
export pgx_instance=<ata instance name>
pgx_pods=`kubectl get pods -n $pgx_ns --sort-by=.status.startTime -o name | awk -F "/" '{print $2}' | grep $pgx_instance-ata-pgx`
pgx_pod_arr=( $pgx_pods )
echo "Deleting pod - ${pgx_pod_arr[0]}"
kubectl delete pod ${pgx_pod_arr[0]} -n $pgx_ns --grace-period=0

The following crontab is scheduled for every day midnight. Scheduled time may vary depending on the volume of data.

Variable $COMMON_CNTK should be set in environment where cronjob runs or replace $COMMON_CNTK with complete path.

crontab –e 0 0 * * * $COMMON_CNTK/samples/cronjob-scripts/pgx-restart.sh > $COMMON_CNTK/samples/cronjob-scripts/pgx-restart.log

If multiple PGX pods are scheduled on the same worker node, the memory consumption by these PGX pods becomes very high. To address this, include the following affinity rule in applications.yaml, under the ata chart to avoid scheduling of multiple PGX pods on the same worker node.

The following podantiaffinity rule uses the app= <topology-project>-<topology-instance>-ata-pgx label. Update the label with the corresponding project and instance names for ATA service. For example: sr-quick-ata-pgx.

ata:
  affinity:
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        - labelSelector:
            matchExpressions:
              - key: app
                operator: In
                values:
                - <topology-project>-<topology-instance>-ata-pgx
          topologyKey: "kubernetes.io/hostname"

When ATA service is involved in secure communication with other systems, either as the server or as the client, you should additionally configure SSL/TLS.The procedures for setting up TLS use self-signed certificates for demonstration purposes. However, replace the steps as necessary to use signed certificates. To generate common self-signed certificates, see "SSL Certificates".

To setup secure communication using TLS:

1. Edit the $SPEC_PATH/sr/quick/applications.yaml and set tls enabled to true.

   tls:
       enabled: true

2. Create the ingressTLS secret to pass the generated certificate and key pem files.

   $COMMON_CNTK/scripts/manage-app-credentials.sh -p sr -i quick -f $COMMON_CNTK/samples/applications.yaml -a ata create ingressTLS

3. The script prompts for the following detail:
   1. Ingress TLS Certificate Path (PEM file): <path_to_commoncert.pem>
   2. Ingress TLS Key file Path (PEM file): <path_to_commonkey.pem>
4. Verify that the following secrets are created successfully.

   sr-quick-ata-ingress-tls-cert-secret

5. Create ATA instance as usual. Access ATA endpoints using hostname <topology-instance>.<topology-instance>.topology.uim.org
6. Add entry in /etc/hosts <k8s cluster ip or external loadbalancer ip> quick.sr.topology.uim.org
7. ATA UI endpoint: https://quick.sr.topology.uim.org:30443/apps/ata-ui
8. ATA API endpoint: https://quick.sr.topology.uim.org:30443/topology/v2/vertex

Smartsearch supports wildcard certificates. You can generate the wildCard certificates with the hostSuffix value provided in applications.yaml. The default is uim.org.

You must change the subDomainNameSeperator value from period(.) to hyphen(-) so that the incoming hostnames match the wild card DNS pattern.

#Uncooment and provide the value of subDomainNameSeparator, default is "."
#Value can be changed as "-" to match wild-card pattern of ssl certificates.
#Example hostnames for "-" quick-sr-topology.uim.org
subDomainNameSeparator: "-"

This section provides you with information on enabling authentication for ATA.

The samples, for using IDCS as Identity Provider, are packaged with ATA. To use any Identity Provider of your choice, you must follow the corresponding configuration instructions.

By default, ATA has its pods scheduled on all worker nodes in the Kubernetes cluster in which it is installed. However, in some situations, you may want to choose a subset of nodes where pods are scheduled.

For example:

Limitation on the deployment of ATA on specific worker nodes per each team for reasons such as capacity management, chargeback, budgetary reasons, and so on.

To choose a subset of nodes where pods are scheduled, you can use the configuration in the applications.yaml file.

Sample node affinity configuration(requiredDuringSchedulingIgnoredDuringExecution) for ATA service:

applications.yaml

ata:
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
        - matchExpressions:
          - key: name
            operator: In
            values:
            - south_zone

Kubernetes pod is scheduled on the node with label name as south_zone. If node with label name: south_zone is not available, pod will not be scheduled.

Sample node affinity configuration (preferredDuringSchedulingIgnoredDuringExecution:) for ATA service:

applications.yaml

ata:
  affinity:
    nodeAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 1
        preference:
          matchExpressions:
          - key: name
            operator: In
            values:
            - south_zone

Kubernetes pod is scheduled on the node with label name as south_zone. If node with label name: south_zone is not available, pod will still be scheduled on another node.

Follow the instructions mentioned in UIM Cloud Native Deployment guide for configuring Kubernetes persistent volumes.

To create persistent storage:

1. Update applications.yaml to enable storage volume for ATA service and provide the persistent volume name.

   storageVolume:
     enabled: true
     pvc: sr-nfs-pvc #Specify the storage-volume name
   

2. Update database.yaml to enable storage volume for ATA dbinstaller and provide the persistent volume name.

   storageVolume:
     enabled: true
     type: pvc
     pvc: sr-nfs-pvc #Specify the storage-volume name
   

After the instance is created, you must see the directories ata and ata-dbinstaller in your PV mount point, if you have enabled logs.

To customize and enable logging, update the logging configuration files for the application.

1. Customize ata-api service logs:
   • For service level logs update file $COMMON_CNTK/charts/ata-app/charts/ata/config/ata-api/logging-config.xml
   • For Helidon-specific logs update file $COMMON_CNTK/charts/ata-app/charts/ata/config/ata-api/logging.properties. By default console handler is used, you can provide filehandler as well uncomment below lines and provide <project> and <instance> names for location to save logs

     handlers=io.helidon.common.HelidonConsoleHandler,java.util.logging.FileHandler
     java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter
     java.util.logging.FileHandler.pattern=/logMount/sr-quick/ata/ata-api/logs/TopologyJULMS-%g-%u.log

2. Customize ata-pgx service logs:

   Update file $COMMON_CNTK/charts/ata-app/charts/ata/config/pgx/logging-config.xml

3. Customize ata-ui service logs:

   Update file $COMMON_CNTK/charts/ata-app/charts/ata/config/ata-ui/logging.properties

4. Update the logging configuration files and upgrade the ata m-s application:

   $COMMON_CNTK/scripts/upgrade-applications.sh -p sr -i quick -f $SPEC_PATH/applications.yaml -a ata

5. Customize the ata-alarm-consumer service log as follows:
   • For service-level logs update file:

     $COMMON_CNTK/charts/ata-app/charts/ata/config/alarm-consumer/logging-config.xml

   • For Helidon-specific logs update file:

     $COMMON_CNTK/charts/ata-app/charts/ata/config/alarm-consumer/logging.properties.

6. Customize SmartSearch Consumer service log:
   • For service level logs update the $COMMON_CNTK/charts/ata-app/charts/ata/config/smartsearch-consumer/logging-config.xml file.
   • For Helidon-specific logs update the $COMMON_CNTK/charts/ata-app/charts/ata/config/smartsearch-consumer/logging.properties file.

You can view and analyze the Application logs using OpenSearch.

The logs are generated as follows:

1. Fluentd collects the application logs that are generated during cloud native deployments and sends them to OpenSearch.
2. OpenSearch collects all types of logs and converts them into a common format so that OpenSearch Dashboard can read and display the data.
3. OpenSearch Dashboard reads the data and presents it in a simplified view.

See "Deleting the OpenSearch and OpenSearch Dashboard Service" for more information.

Run the following endpoint to monitor metrics of ATA:

https://instance.project.topology.<hostSuffix>:<loadbalancerport>/metrics

Prometheus and Grafana setup

See "Setting Up Prometheus and Grafana" for more information.

Adding scrape Job in Prometheus

Add the following Scrape job in Prometheus Server. This can be added by editing the config map used by the Prometheus server:

- job_name: 'topologyApiSecuredMetrics'
      oauth2:
        client_id: <client-id>
        client_secret: <client-secret>
        scopes:
          - <Scope>
        token_url: <OAUTH-TOKEN-URL>
        tls_config:
          insecure_skip_verify: true
      kubernetes_sd_configs:
      - role: pod
      relabel_configs:
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
        action: keep
        regex: true
      - source_labels: [__meta_kubernetes_pod_label_app]
        action: keep
        regex: (<project>-<instance>-ata-api)
      - source_labels: [__meta_kubernetes_pod_container_port_number]
        action: keep
        regex: (8080)
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
        action: replace
        target_label: __metrics_path__
        regex: (.+)
      - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
        action: replace
        regex: ([^:]+)(?::\d+)?;(\d+)
        replacement: $1:$2
        target_label: __address__
      - action: labelmap
        regex: __meta_kubernetes_pod_label_(.+)
      - source_labels: [__meta_kubernetes_namespace]
        action: replace
        target_label: kubernetes_namespace
      - source_labels: [__meta_kubernetes_pod_name]
        action: replace
        target_label: kubernetes_pod_name

To increase performance of the service, applications.yaml has configuration to provide JVM memory settings and pod resources for ATA Service.

There are separate configurations provided for ata-api, topology-consumer, alarm-consumer, smartsearch-consumer, pgx, and ata-ui services. Provide required values under the service name under ata application.

ata:
  topologyApi:
    apiName: "ata-api"
    replicaCount: 3
    java:
      user_mem_args: "-Xms2000m -Xmx2000m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/logMount/$(APP_PREFIX)/ata/ata-api/"
      gc_mem_args: "-XX:+UseG1GC"
      options:
    resources:
      limits:
        cpu: "2"
        memory: 3Gi
      requests:
        cpu: 2000m
        memory: 3Gi

Provide replica count in applications.yaml to scale up or scale down the ATA pods. Replica count can be configured for ata-api, topology-consumer, alarm consumer, pgx, and ata-ui pods individually by updating applications.yaml.

Update applications.yaml to increase replica count to 3 for ata-api deployment.

ata:
  topologyApi:
    replicaCount: 3

Apply the change in replica count to the running Helm release by running the upgrade-applications script.

$COMMON_CNTK/scripts/upgrade-applications.sh -p sr -i quick -f $SPEC_PATH/sr/quick/applications.yaml -a ata

By default, GC logs are disabled, you can enable them and view the logs at the corresponding folders inside location /logMount/sr-quick/ata.

To Enable GC logs, update $SPEC_PATH/sr/quick/applications.yaml file as follows:

1. Under gcLogs make enabled as true you can uncomment gcLogs options under ata to override the common values.
2. To configure the maximum size of each file and limit for number of files you need to set fileSize and noOfFiles inside gcLogs as follows:

   gcLogs:
     enabled: true
     fileSize: 10M
     noOfFiles: 10

The following figure illustrates the fallout events resolution process flow for topology consumer.

Figure 8-2 Process Flow of Fallout Events Resolution for Topology Consumer

Description of "Figure 8-2 Process Flow of Fallout Events Resolution for Topology Consumer"

These failed events in the TOPOLOGY_FALLOUT_EVENTS table can be rebuilt and resubmitted for the specific target service identifier. The target service value used for the topology consumer is ATA. When a fallout event comes into the table, it is in PENDING state. These events can be Rebuilt or Resubmitted as follows:

• REBUILD: This action processes the Fallout Event and gets any out of sync data from UIM into ATA through the Database Link.

• RESUBMIT: This action takes the events from the TOPOLOGY_FALLOUT_EVENTS table in PENDING or READY_TO_RESUBMIT states and moves them back into the ora_retry_topology topic for re-processing.

The events will be stored into topology fallout event table when the SmartSearch consumer service is not able to process successfully due to some possible technical and data validation issues.

Description of the illustration fallout_res_events_ssconsumer.png

The fallout resolution for a SmartSearch consumer is as follows:

1. The message producer sends event and message to the topic (ora_uim_topology).
2. The SmartSearch consumer receives the event and message from the topic (ora_uim_topology).
3. It invokes the SmartSearch bulk API to persist the event or message in Open Search.
4. If the SmartSearch bulk API not able to process the even or message, or SmartSearch consumer is not able to process then the SmartSearch consumer sends a message to retry the topic (ora-retry-smartsearch).
5. The SmartSearch consumer retries again to process. If still not processed, then the SmartSearch consumer sends an event message to the Dead Letter topic (ora-dlt-smartsearch).
6. The DLT process of SmartSearch consumer gets event or message from the Dead Letter topics that persist in the TOPOLOGY_FALLOUT_EVENTS table.

The fallout resolution starts analyzing from the topology fallout events for the specific target service. The target service value used for SmartSearch consumer is SSC. The resolution can be performed with the help of fallout resolution REST APIs.

For full list of REST APIs, see REST API for ATA for Inventory and Automation.

The following image illustrates an alarm event (or message) processing flow in alarm consumer.

Figure 8-3 Fallout Events Resolution for Alarm Consumer

Description of "Figure 8-3 Fallout Events Resolution for Alarm Consumer"

In highly secured installations, you may not provide internet access to the location. In such situations, Oracle recommends using an allowlist solution so the base maps can include the streets, cities, buildings, and so on.

For the map tiles to render, allowlist the following URLs:

• Tile 1:
  • http://a.tile.openstreetmap.org/11/472/824.png
  • http://b.tile.openstreetmap.org/11/472/825.png
  • http://c.tile.openstreetmap.org/11/472/825.png
• Tile 2:
  • http://a.tiles.mapbox.com/v4/mapbox.satellite/10/236/412@2x.png?access_token=pk.eyJ1IjoidzhyIiwiYSI6ImNpeGhwaXF1ejAwMHQydG8yZ3pyanZ5aTkifQ.QNScWNGnLRHIHXeAsGMvyw
  • http://b.tiles.mapbox.com/v4/mapbox.satellite/10/235/411@2x.png?access_token=pk.eyJ1IjoidzhyIiwiYSI6ImNpeGhwaXF1ejAwMHQydG8yZ3pyanZ5aTkifQ.QNScWNGnLRHIHXeAsGMvyw
  • http://c.tiles.mapbox.com/v4/mapbox.satellite/10/236/411@2x.png?access_token=pk.eyJ1IjoidzhyIiwiYSI6ImNpeGhwaXF1ejAwMHQydG8yZ3pyanZ5aTkifQ.QNScWNGnLRHIHXeAsGMvyw
• Tile 3:
  • http://a.basemaps.cartocdn.com/light_all/10/235/412@2x.png
  • http://b.basemaps.cartocdn.com/light_all/10/235/412@2x.png
  • http://c.basemaps.cartocdn.com/light_all/10/235/412@2x.png
• Tile 4:
  • http://a.basemaps.cartocdn.com/dark_all/10/236/413@2x.png
  • http://b.basemaps.cartocdn.com/dark_all/10/236/413@2x.png
  • http://c.basemaps.cartocdn.com/dark_all/10/236/413@2x.png
• Tile 5: http://server.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer/tile/10/412/235
• Tile 6: http://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/10/412/236

To set up a local tile server, you must deploy the prepared tile files on a local server. Every file must have its direct link: http://tileserver.com/{z}/{y}/{x}. This format allows getting the required response for the request http://tileserver.com/{z}/{x}/{y}.png.

Contact your system administrator to install, deploy, and run your own tile server. The configuration process is dependent on the tile server you choose to implement. The tile server requires high computing power and requires operations support and maintenance.

The tile server is responsible for caching the tiles, sharing the load, and processing the request queue at regular intervals.

You can consider some options available in the market such as MapTiler, QGIS, Switch2OSM, ArcGis Enterprise, and so on.

After you set up the tile server and a successful deployment, you can access the map tiles through APIs in the format: http://{hostname}:{port}/{baseUrl}/{z}/{x}/{y}.png.