Merge pull request #2535 from splunk/stran-O11YDOCS-6651-data-links-ui

[O11YDOCS-6651] Global data links to AppDynamics tiers

Author: sheilattran8

_images/apm/apm-data-links/appd-data-links-sample-csv.png

@@ -0,0 +1,78 @@
+.. _apm-create-data-links-terraform-batch:
+
+**************************************************************************************
+Create a batch of global data links to Splunk AppDynamics tiers with a Node.js script
+**************************************************************************************
+
+.. meta::
+   :description: Learn how to use a Node.js script to create a batch of global data links to Splunk AppDynamics tiers.
+
+.. note::
+    You can only create a global data link from a Splunk APM inferred service to a Splunk AppDynamics tier if the tier is monitored by a Splunk AppDynamics SaaS environment.
+
+    This method can only be used to create global data links for inferred services that do not have existing global data links. If your inferred service already has an existing global data link, :ref:`use the UI <apm-create-gdl-to-appd>` to create additional global data links.
+
+When a transaction goes through a service monitored by Splunk APM as well as a tier monitored by Splunk AppDynamics, the service monitored by Splunk APM is considered an inferred service.
+
+Create a global data link to link a Splunk APM inferred service to a Splunk AppDynamics tier. When you view the inferred service in Splunk APM, you can select the data link to navigate to the tier in the Splunk AppDynamics user interface.
+
+You can programmatically create global data links to Splunk AppDynamics tiers with a CSV file and Splunk Node.js script, which generates and runs a Terraform script that creates the data links. This process does not require running Terraform commands.
+
+Prerequisites
+=================
+
+To create a global data link to a Splunk AppDynamics tier using the Node.js script, you need:
+
+* A Splunk Observability Cloud account with the admin role. 
+* Node.js version 20.18.1 or higher.
+* The latest version of Terraform.
+
+Create a batch of global data links
+======================================
+
+To create a batch of global data links:
+
+#. Create a CSV file to define the data links you want to create. The CSV file must match the following format, which uses three columns to denote the OllyInferredServiceName, AppDLinkLabel, and AppDLink: 
+    .. image:: /_images/apm/apm-data-links/appd-data-links-sample-csv.png
+        :width: 100%
+        :alt: This image shows a sample file for creating a batch of global data links to Splunk AppDynamics.
+
+    - For OllyInferredServiceName, enter the Splunk APM inferred service name.
+    - For AppDLinkLabel, enter a label for the data link. This label appears in the Splunk O11y user interface.
+    - For AppDLink, enter the Splunk AppDynamics tier URL.
+        To obtain the tier URL, navigate to the tier in the Splunk AppDynamics UI and copy the URL from the browser. Ensure that you capture the entire URL and that it contains the controller URL, application ID, and application component.
+
+#. Download the Node.js script from the :new-page:`Splunk GitHub repository <https://github.com/splunk/appd-centric-batch-data-link-creator>`. The Node.js script uses the CSV file as an input to generate and run a Terraform script that creates the data links.
+
+#. To install the dependencies in the Node.js script package, run: 
+    .. code-block:: none
+
+        npm install
+
+#. To run the Node.js script, run:
+    .. code-block:: none
+
+        node createAppDLinkTerraformScript.js <csv-file-path> <o11y-api-url> <o11y-auth-token>
+
+    - For <csv-file-path>, enter the file path to the CSV file you created.
+    - For <o11y-api-url>, enter the API URL for your Splunk Observability Cloud environment. To obtain it, navigate to Splunk Observability Cloud and select your profile in the header. Select :guilabel:`My Profile`, then :guilabel:`Organizations`, and copy the :guilabel:`API Endpoint`.
+    - For <o11y-auth-token>, enter your Splunk Observability Cloud API access token. To obtain it, navigate to Splunk Observability and select your profile in the header. Select :guilabel:`My Profile`, then :guilabel:`Show User API Access Token`, and copy the API access token.
+
+    This command creates the following files in the Terraform directory:
+        - appDDataLink.tf: The Terraform configuration file, which contains the Splunk Observability Cloud environment details and the data links from the CSV file.
+        - appDLink_Plan.tf: The Terraform plan file, which contains the list of changes that Terraform will make. 
+        - terraform.tfstate: The Terraform state file, which contains the list of resources that Terraform successfully created.
+
+#. To verify that the global data links were successfully created, use one of the following methods:
+    #. View the output of the command. Sample output for a successful execution: ``Apply complete! Resources: 3 added, 0 changed, 0 destroyed``.
+    #. View the terraform.tfstate file in the Terraform directory, which contains the list of created resources.
+    #. View the global data links in the UI. In the Splunk Observability Cloud main menu, select :guilabel:`Settings` then :guilabel:`Global Data Links`. Search the page for the AppDLinkLabel names that you specified in the CSV file.
+
+#. To troubleshoot errors, view the APPD_LINK_TF_LOGS.log file in the Terraform directory. The log file is organized by the timestamp that the Node.js script executed the Terraform script.
+
+Next steps
+============
+
+To access global data links in the user interface, see :ref:`apm-access-gdl-service`.
+
+To delete all global data links using Terraform, see :ref:`apm-delete-data-links-terraform`.

apm/apm-data-links/apm-create-data-links.rst

@@ -0,0 +1,174 @@
+.. _apm-create-data-links-terraform-file:
+
+*****************************************************************************
+Create global data links to Splunk AppDynamics tiers with a Terraform file
+*****************************************************************************
+
+.. meta::
+   :description: Learn how to use a Terraform configuration file to create global data links to Splunk AppDynamics tiers.
+
+.. note::
+    You can only create a global data link from a Splunk APM inferred service to a Splunk AppDynamics tier if the tier is monitored by a Splunk AppDynamics SaaS environment.
+
+    This method can only be used to create global data links for inferred services that do not have existing global data links. If your inferred service already has an existing global data link, :ref:`use the UI <apm-create-gdl-to-appd>` to create additional global data links.
+
+When a transaction goes through a service monitored by Splunk APM as well as a tier monitored by Splunk AppDynamics, the service monitored by Splunk APM is considered an inferred service.
+
+Create a global data link to link a Splunk APM inferred service to a Splunk AppDynamics tier. When you view the inferred service in Splunk APM, you can select the data link to navigate to the tier in the Splunk AppDynamics user interface.
+
+You can programmatically create global data links to Splunk AppDynamics tiers with a Terraform configuration file.
+
+Prerequisites
+=================
+
+To create a global data link to a Splunk AppDynamics tier using the Node.js script, you need:
+
+* A Splunk Observability Cloud account with the admin role. 
+* The latest version of Terraform.
+
+Create data links with a Terraform configuration file
+========================================================
+
+To create data links with a Terraform configuration file:
+
+#. In the Terraform directory, create a Terraform configuration file named <file-name>.tf with the following contents:
+    .. code-block:: terraform
+
+        # Specify the Terraform provider and version
+        terraform {
+        required_providers {
+            signalfx = {
+            source  = "splunk-terraform/signalfx"
+            version = "~> <current-splunk-terraform-provider-version>"
+            }
+        }
+        }
+
+        # The following variable blocks can also be located in a variables.tf file in the same directory
+        variable "signalfx_auth_token" {
+        description = "The user API access authentication token for your org"
+        type        = string
+        default     = ""
+        }
+        variable "signalfx_api_url" {
+        description = "The API URL of your org"
+        type        = string
+        default     = ""
+        }
+
+        # Configure the Splunk Observability Cloud provider
+        provider "signalfx" {
+        auth_token = "${var.signalfx_auth_token}"
+        api_url = "${var.signalfx_api_url}"
+        }
+
+    - For ``version``, enter the current Splunk Observability Cloud Terraform provider version. To check the latest version, see :new-page:`Releases <https://github.com/splunk-terraform/terraform-provider-signalfx/releases>`. This value must be 9.6.0 or higher.
+    - (Optional) Add arguments as needed for your configuration. For more information on the supported arguments, see :new-page:`Splunk Observability Cloud provider <https://registry.terraform.io/providers/splunk-terraform/signalfx/latest/docs#arguments>` in the Terraform documentation.
+
+#. Add the :new-page:`signalfx_data_link <https://registry.terraform.io/providers/splunk-terraform/signalfx/latest/docs/resources/data_link>` resource to the Terraform file:
+    .. code-block:: none
+
+        # A link to a Splunk AppDynamics service
+        resource "signalfx_data_link" "<data-link-id>" {
+        property_name        = "sf_service"
+        property_value       = "<splunk-inferred-service-name>"
+
+        target_appd_url {
+            name        = "<data-link-ui-label>"
+            url         = "<https://www.example.saas.appdynamics.com/#/application=1234&component=5678>"
+        }
+        }
+
+    - For <data-link-id>, enter an identifier for the data link. This value is only visible in the Terraform file and must be unique for each data link. For example, you can use my_data_link_appd_1 or my_data_link_appd_2.
+    - For ``property_name``, use ``sf_service``.
+    - For ``property_value``, enter the Splunk APM inferred service name.
+    - For ``name``, enter a label for the data link. This label appears in the Splunk Observability Cloud user interface.
+    - For ``URL``, enter the Splunk AppDynamics tier URL.
+        To obtain the tier URL, navigate to the tier in the Splunk AppDynamics UI and copy the URL from the browser. Ensure that you capture the entire URL and that it contains the controller URL, application ID, and application component.
+
+#. Repeat the previous step for each data link to a Splunk AppDynamics tier you want to create. The following example displays a Terraform configuration file with multiple data links to Splunk AppDynamics tiers:
+    .. code-block:: terraform
+
+        # Specify the Terraform provider and version
+        terraform {
+        required_providers {
+            signalfx = {
+            source  = "splunk-terraform/signalfx"
+            version = "~> 9.6.0"
+            }
+        }
+        }
+
+        # The following variable blocks can also be located in the variables.tf file in the same directory
+        variable "signalfx_auth_token" {
+        description = "The user API access auth token for your org"
+        type        = string
+        default     = ""
+        }
+        variable "signalfx_api_url" {
+        description = "The API URL of your org"
+        type        = string
+        default     = ""
+        }
+
+        # Configure the Splunk Observability Cloud provider
+        provider "signalfx" {
+        auth_token = "${var.signalfx_auth_token}"
+        api_url    = "${var.signalfx_api_url}"
+        }
+        # If your organization uses a custom URL, replace api_url with:
+        # custom_app_url = "https://myorg.signalfx.com"
+
+        # A link to a Splunk AppDynamics service
+        resource "signalfx_data_link" "my_data_link_appd_1" {
+        property_name        = "sf_service"
+        property_value       = "placed_orders"
+
+        target_appd_url {
+            name        = "appd_url_placed_orders"
+            url         = "https://www.example.saas.appdynamics.com/#/application=1234&component=5678"
+        }
+        }
+
+        # A link to a Splunk AppDynamics service
+        resource "signalfx_data_link" "my_data_link_appd_2" {
+        property_name        = "sf_service"
+        property_value       = "returned_orders"
+
+        target_appd_url {
+            name        = "appd_url_returned_orders"
+            url         = "https://www.example.saas.appdynamics.com/#/application=4321&component=8765"
+        }
+        }
+
+#. In the working directory with your Terraform configuration file, run the following command to initialize the directory:
+    .. code-block:: none
+
+        terraform init
+
+#. To set your signalfx_auth_token and signalfx_api_url variables and generate a preview of the changes that Terraform will make, run:
+    .. code-block:: none
+
+        terraform plan -var="signalfx_auth_token=<api-access-token>" -var="signalfx_api_url=https://api.<realm>.signalfx.com" -out=<plan-file-name>
+        
+    - For <api-access-token>, enter your Splunk Observability Cloud API access token. To obtain it, navigate to Splunk Observability and select your profile in the header. Select :guilabel:`My Profile`, then :guilabel:`Show User API Access Token`, and copy the API access token.
+    - For <realm>, enter your Splunk Observability Cloud realm. To obtain your realm, navigate to Splunk Observability Cloud and select your profile in the header. Select :guilabel:`My Profile`, then :guilabel:`Organizations`, and copy the :guilabel:`Realm`.
+    - For <plan-file-name>, enter your desired name for the plan file that Terraform will create for the changes.
+
+#. Use the output to review the changes. To run the changes and create a terraform.tf.state file that lists the resources that Terraform created:
+    .. code-block:: none
+
+        terraform apply "<plan-file-name>"
+
+#. To verify that the global data links were successfully created, use one of the following methods:
+    - View the output of the command. Sample output for a successful execution: ``Apply complete! Resources: 3 added, 0 changed, 0 destroyed``.
+    - View the terraform.tfstate file in the Terraform directory, which contains the list of created resources.
+    - View the global data links in the UI. In the Splunk Observability Cloud main menu, select :guilabel:`Settings` then :guilabel:`Global Data Link`. Search the page for the data link name that you specified in the Terraform file.
+
+Next steps
+=============
+
+To access global data links in the user interface, see :ref:`apm-access-gdl-service`.
+
+To delete all global data links using Terraform, see :ref:`apm-delete-data-links-terraform`.
+

apm/apm-data-links/apm-datalinks-terraform/apm-create-data-links-terraform-batch.rst

@@ -0,0 +1,31 @@
+.. _apm-create-data-links-terraform:
+
+*********************************************************************
+Manage global data links to Splunk AppDynamics tiers with Terraform
+*********************************************************************
+
+.. meta::
+   :description: An overview of how to use Terraform to create and delete global data links to Splunk AppDynamics tiers.
+
+.. toctree::
+      :hidden:
+      :maxdepth:  3
+
+      apm-create-data-links-terraform-batch
+      apm-create-data-links-terraform-file
+      apm-delete-data-links-terraform
+
+.. note::
+    You can only create a global data link from a Splunk APM inferred service to a Splunk AppDynamics tier if the tier is monitored by a Splunk AppDynamics SaaS environment.
+
+When a transaction goes through a service monitored by Splunk APM as well as a tier monitored by Splunk AppDynamics, the service monitored by Splunk APM is considered an inferred service.
+
+Create a global data link to link a Splunk APM inferred service to a Splunk AppDynamics tier. When you view the inferred service in Splunk APM, you can select the data link to navigate to the tier in the Splunk AppDynamics user interface.
+
+Using Terraform, you can programmatically:
+
+* (Recommended) :ref:`apm-create-data-links-terraform-batch`
+* :ref:`apm-create-data-links-terraform-file`
+* :ref:`apm-delete-data-links-terraform`
+
+To create a data link using the user interface, see :ref:`apm-create-gdl-to-appd`. The user interface only supports creating one data link at a time.

apm/apm-data-links/apm-datalinks-terraform/apm-create-data-links-terraform-file.rst

@@ -0,0 +1,40 @@
+.. _apm-delete-data-links-terraform:
+
+*********************************************
+Delete all global data links with Terraform
+*********************************************
+
+.. meta::
+   :description: Learn how to use Terraform to delete all global data links created with Terraform.
+
+Use Terraform to programmatically delete all global data links that you created with Terraform. This process deletes all of the global data links in the terraform.tf.state file in the Terraform directory.
+
+Prerequisites
+===============
+
+To delete global data links with Terraform, you need:
+
+* A Splunk Observability Cloud account with the admin role. 
+* The latest version of Terraform.
+* Global data links created with Terraform, either with the :ref:`Node.js script<apm-create-data-links-terraform-batch>` or the :ref:`Terraform file<apm-create-data-links-terraform-file>`.
+
+Delete all global data links with Terraform
+=============================================
+
+To delete all global data links that you created with Terraform:
+
+#. View the terraform.tf.state file in the Terraform directory. Confirm that you want to delete all of the data links in the file.
+
+#. Open your terminal and navigate to the Terraform directory. Run:
+     .. code-block:: none
+
+        terraform destroy -var="signalfx_auth_token=<api-access-token>" -var="signalfx_api_url=https://api.<realm>.signalfx.com"
+    
+    - For <api-access-token>, enter your Splunk Observability Cloud API access token. To obtain it, navigate to Splunk Observability and select your profile in the header. Select :guilabel:`My Profile`, then :guilabel:`Show User API Access Token`, and copy the API access token.
+    - For <realm>, enter your Splunk Observability Cloud realm. To obtain your realm, navigate to Splunk Observability Cloud and select your profile in the header. Select :guilabel:`My Profile`, then :guilabel:`Organizations`, and copy the :guilabel:`API Endpoint`.
+
+#. View the UI to confirm that the data links were deleted:
+    #. In the Splunk Observability Cloud main menu, select :guilabel:`Settings` then :guilabel:`Global Data Link`.
+    #. Search for the names of the data links you created.
+        - If you used the :ref:`Node.js script method <apm-create-data-links-terraform-batch>`, search for the AppDLinkLabel values that you specified in the CSV file.
+        - If you used the :ref:`Terraform file method <apm-create-data-links-terraform-file>`, search for the ``name`` values that you specified in the Terraform configuration file.

apm/apm-data-links/apm-datalinks-terraform/apm-data-links-terraform.rst

@@ -13,10 +13,14 @@ For example, you can use a global data link to easily navigate from an APM prope
 
 For information about creating global data links, see :ref:`apm-create-data-links`.
 
+.. _apm-access-gdl-service:
 
 Access global data links for a service
 =========================================
 
+.. note::
+    For global data links to Splunk AppDynamics: If selecting the global data link does not load a tier in the Splunk AppDynamics user interface, check if Splunk AppDynamics has data for the time range. If there is no data for the time range and Splunk AppDynamics is experiencing issues, contact  :new-page:`Splunk AppDynamics support <https://www.splunk.com/en_us/customer-success/appdynamics-support.html>`.
+
 **To access global data links for a service on the Overview page:**
 
 #. Open the Splunk Observability Cloud main menu.
@@ -37,7 +41,6 @@ Access global data links for a service
 
 #. In the service detail drawer, select the :guilabel:`More` icon next to the service name. The menu displays global data links for the service.
 
-
 Access global data links for a trace
 =======================================