Updates to data source chapter

Author: mitoeth

manageability-and-operations/observability-and-manageability/application-performance-monitoring/LZ-addons/apm-lz-design-decisions.md

@@ -47,35 +47,35 @@ If it's decided to move from a free to a paid APM domain, it's possible to **exp
 
 ### Data sources
 
-A data source is any component made to collect data from applications for the sake of monitoring. It's important to clarify the programming languages, application servers, and frameworks used by the application environment to determine what data sources can be used for the APM domain. OCI APM provides Java and .NET agents for back-end monitoring out-of-the-box. These back-end agents are also able to automatically inject the browser agent as JavaScript for front-end monitroring. Click [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/configure-application-performance-monitoring-data-sources.html) for more about the deployment and configuration of these out-of-the-box data sources. Click [here](https://mosemp.us.oracle.com/epmos/faces/DocumentDisplay?id=2759709.1) to see what kinds of application environments they support.
+A data source is any component made to collect data from applications for the sake of monitoring. It's important to **clarify the programming languages, application servers, and frameworks** used by the application environment to determine what data sources can be used for the APM domain. OCI APM provides Java and .NET agents for back-end monitoring out-of-the-box. These back-end agents are also able to automatically inject the browser agent as JavaScript for front-end monitroring. Click [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/configure-application-performance-monitoring-data-sources.html) for more about the deployment and configuration of these out-of-the-box data sources. Click [here](https://mosemp.us.oracle.com/epmos/faces/DocumentDisplay?id=2759709.1) to see what kinds of application environments they support.
 
 ![APM Data Sources](../images/apm_data_source_diagram.png)
 
 In cases where certain application services are not compatible with APM's own back-end data sources or cannot use the automatic injection of the browser agent JavaScript, the following options should be considered instead:
 
 * **APM Java tracer**. When the APM Java agent is somehow not workable for the application environment, the APM Java tracer is available as well to collect trace data and JVM metrics. Click [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/configure-apm-tracer.html) for more about the APM Java tracer.
 * **OpenTelemetry tracers**. For programming languages outside of Java and .NET, OCI APM is compatible with any tracer following the OpenTelemetry standard. A good starting point is to check the official OpenTelemetry website (click [here](https://opentelemetry.io/) for more) for available stable tracers developed by the community. These tracers would need to export the data using the endpoint and private key of the APM domain (click [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/configure-open-source-tracing-systems.html) for more).
-* **Manual injection of browser agent JavaScript**. Whenever automatic injection is not possible, the JavaScript can be manually added to web application pages for front-end monitoring. Make sure to find an appropriate and efficient way to add the JavaScript, so all necessary browser actions are captured (click [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/deploy-browser-agent-your-application.html) for more).
+* **Manual injection of browser agent JavaScript**. Whenever automatic injection is not possible, the JavaScript can be manually added to web application pages for front-end monitoring. Make sure to find an appropriate and efficient way to add the JavaScript, so all necessary browser actions are captured. For example, add the JavaScript to a global template rather than individual pages (click [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/deploy-browser-agent-your-application.html) for more).
 
-Any data source needs to be able to reach the APM domain endpoint via HTTPS (Port 443) using either the private or public key. See section 3 for more about the overall deployment scenario.
+Any data source needs to be able to reach the APM domain endpoint via HTTPS (Port 443) using either the private or public key. See the [deployment blueprint](apm-lz-deployment-scenario.md) for more about the overall deployment scenario.
 
-As an optional extension, data sources can be configured to personalize what and how application data is collected . Data sources like APM agents or OpenTelemetry tracers will instrument applications according to general requirements common to most scenarios. Data sources with default settings do not consider any requirements applying to specific applications such as correlating performance to specific business logic or adjusting the resource usage caused by data collection. While data sources are configured to be as useful and as efficient as possible for most situations, it's important to identify any unique requirments applying to the application and configure the data sources as needed.
+As an optional extension, data sources can be configured to personalize what and how application data is collected. Data sources like APM agents or OpenTelemetry tracers will instrument applications according to general requirements common to most scenarios. Data sources with default settings do not consider any requirements applying to specific applications such as correlating performance to specific business logic or adjusting the resource usage caused by data collection. While data sources are configured to be as useful and as efficient as possible for most situations, it's important to identify any unique requirments applying to the application and configure the data sources as needed.
 
 Data source configurations either serve to modify collected data or the amount of resources consumed by the data collection process:
 
-* **OCI APM back-end agents for Java and .NET applications**. There are many configurations that can be done for these agents. Please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/optional-configuration-tasks.html) for all configurations options available to the APM Java agent. Please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/perform-optional-configuration-tasks-dotnet-agent.html) for all configuration options available to the APM .NET agent. In this section, the following configuration options will be high-lighted:
+* **OCI APM back-end agents for Java and .NET applications**. There are many configurations that can be done for these agents. Please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/optional-configuration-tasks.html) for all configuration options available to the APM Java agent. Please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/perform-optional-configuration-tasks-dotnet-agent.html) for all configuration options available to the APM .NET agent. In this section, the following configuration options will be high-lighted:
   * **Java probe configurations**. The APM Java agent consists of probes instrumenting different application components to collect certain traces with certain context attributes. It's possible to modify or enable/disable agent probes in the config file ProbeConfig.acml. It's also possible to create a custom probe which instrument and monitor additional classes for application-specific details applying to unique requirments. For more about modifying agent probes, please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/modify-probe-settings.html).
   * **Custom Java application server metrics**. The APM Java agent collects server metrics such as CPU, heap usage, and garbage collection. It's also possible to define custom metrics extracted from MBeans. Please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/metrics-collection.htm) for more.
   * **Thread snapshots**. The APM Java agent is able to collect Java thread snapshots related to traces and spans for callstack visibility. This agent feature is disabled by default. Please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/configure-thread-snapshots-apm-agent.html) for more.
-  * **Abridged traces**. This reduces the amount of spans captured for a trace according to certain settings. A good example is database call spans. Whenever an applications performs many database calls, traces can be abridged to only include database call spans which exceed e.g., 10 milliseconds. This way, only slow database calls are captured in traces which reduces noise and makes analysis easier. Please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/introduction-apm-java-agent.html#GUID-FF58739D-5C53-4192-8342-D4452AAFD78F__GUID-FB079806-D2A9-4768-94C5-26E8DFD4BB04) for more.
+  * **Abridged traces**. This reduces the amount of spans captured for a trace according to certain settings. A good example is database call spans. Whenever an application performs many database calls, traces can be abridged to only include database call spans which exceed e.g., 10 milliseconds. This way, only slow database calls are captured in traces which reduces noise and makes analysis easier. Please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/introduction-apm-java-agent.html#GUID-FF58739D-5C53-4192-8342-D4452AAFD78F__GUID-FB079806-D2A9-4768-94C5-26E8DFD4BB04) for more.
   * **Circuit breakers**. These are settings disabling the APM agent due to overhead caused by heap memory usage and garbage collection time. APM agents are generally configured to consume as few resources as possible, but does still come with default circuit breaker settings if necessary. These settings can also be adjusted if needed. Please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/introduction-apm-java-agent.html#GUID-FF58739D-5C53-4192-8342-D4452AAFD78F__GUID-3C8DBEF1-C47B-4C5C-99BF-4280703C4FA8) for more.
 * **OCI APM browser agent for front-end monitoring**. The browser agent is written in JavaScript and can technically be rewritten as needed. However, this should be done carefully to avoid unexpected effects. It's adviced to follow guidelines for the browser agent in official OCI APM documentation (click [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/configure-browser-agent-real-user-monitoring.html) for more). In this section, the following configuration options will be high-lighted:
   * **Automatic injection settings**. The APM back-end agents can be configured to automatically inject the browser agent code into appropriate web application pages. This is recommended for most use cases to simplify setup. The injection can also be configured with different settings or be disabled to remove JavaScript previously injected. For more about this, please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/inject-apm-browser-agent-using-apm-java-agent.html) for APM Java agent, and [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/configure-apm-browser-agent-injection-using-apm-dotnet-agent.html) for the APM .NET agent.
   * **User name capture**. This part of the browser agent often needs to be customized because the user name is collected differently from application to application. Please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/configure-attributes-real-user-monitoring.html#GUID-B668189F-72E6-4585-803D-E73448B47A92__GUID-0EE1C333-A87A-4491-9BC1-E271A92E52BE) for more.
   * **Custom span attributes**. It's possible to add JavaScript which collects values saved as custom context attributes to browser spans using the udfAttributes property of the apmrum JavaScript object. Please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/configure-attributes-real-user-monitoring.html#GUID-B668189F-72E6-4585-803D-E73448B47A92__GUID-13D78B7F-81D0-4F5B-9F99-BF9BE2F57682) for more.
   * **Context propagation headers for Ajax calls**. End-to-end tracing in OpenTelemetry works by sharing trace context from span to span. This way the next span will know it's a continuation of a trace started by a root span. When Ajax calls are made from browsers to servers, trace context is propagated by adding it to requests as special headers. OCI APM browser and back-end agents already know how to propagate trace context to each other. For use cases involving 3rd party OpenTelemetry tracers, it's recommended to review the exact propagation headers they use. Ensure the APM browser agent uses the same propagation format during Ajax calls. Please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/configure-automatic-end-end-tracing-same-domain.html#GUID-37C5A79C-F02E-475F-8381-85E68F874701__GUID-71BF84E4-46DC-46F7-86EB-490E56EE721A) for more.
 * **Sampling**. This is a trace collection technique to capture a fraction of the trace data based on sampling rules for the traces' root spans. If a rule applies to a root span, the entire trace is sampled. Everything else is ignored. When defining rules, sampled data should be seen as representatives for everything that isn't sampled. That way, data volume is reduced while still collecting meaningful traces. For more about sampling with the APM Java agent, please see [here](https://docs.oracle.com/en-us/iaas/application-performance-monitoring/doc/configure-apm-sampling-apm-agent.html) for more.
-* **OpenTelemetry tracers**. Review any available documentation for any selected 3rd party tracer. As mentioned previously in section 2.1, you can set an enrichment rule in the APM domain to convert OpenTelemetry semantic conventions to OCI APM naming conventions. This is recommended when using a non-Oracle tracer.
+* **OpenTelemetry tracers**. Review any available documentation for any selected 3rd party tracer. As mentioned previously in [Domains](#domains), you can set an enrichment rule in the APM domain to convert OpenTelemetry semantic conventions to OCI APM naming conventions. This is recommended when using a non-Oracle tracer.
  
 
 ### Availability Monitors