### Instana REST API Getting Started Prerequisites

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=api-examples

Before using the Instana REST API, ensure you have an active Instana account with API access, and that Curl and Python are installed on your machine. General prerequisites include an API token with appropriate permissions and the correct Base URL.

```APIDOC
## Getting started
Before you begin, make sure that you have the following requirements:
  * An active Instana account with API access
  * Curl and Python installed on your machine

### General prerequisites
To use the identified Instana REST API endpoints in this tutorial, you need the following information:

| Requirement | Description | Where to find it |
|---|---|---|
| API token | An API token with the appropriate permissions to query the data. In most cases, special permissions are not needed to access data. | For more information about how to create and access your API token, see the Getting Started guide. |
| Base URL | The base URL is the URL you use to access the Instana UI (For more information, see this reference). The base URL consists of your tenant and unit. | The base URL must have the form `https://{tenant}-{unit}.instana.io`. 
```

--------------------------------

### Interactive Instana Installation Prompts

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=installing-standard-edition-in-online-environment

These are example prompts encountered during a non-silent Instana installation. They guide the user to provide necessary configuration details such as installation type, keys, domain, tenant name, unit name, password, and TLS certificate information.

```text
? Choose installation type: demo
? Enter the download key or an official agent key: **********************
? Enter the sales key: **********************
? Enter the domain under which Instana will be reachable: instana.example.com
? Enter your tenant name: marketing
? Enter your unit name: test
? Enter Instana admin password: *****
? Confirm Instana admin password: *****
? Enter TLS certificate file (hit ENTER to auto-generate):

```

--------------------------------

### Instana REST API - Getting Started

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=examples-retrieving-services-trace-data

An introduction to the Instana REST API, covering initial setup and concepts.

```APIDOC
## Instana REST API - Getting Started

This section provides an introduction to the Instana REST API, including how to get started with its usage and common concepts.
```

--------------------------------

### Start Instana Agent using setup_agent_airgapped.sh Script (Shell)

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=agents-installing-zos-unix-system-services-uss

These commands demonstrate how to make the agent installation script executable, set the file tag, and then run the script to start the Instana agent. This is used when the script was transferred via SCP or SFTP.

```shell
bash
chmod +x ./setup_agent_airgapped.sh && chtag -R -tc 819 ./setup_agent_airgapped.sh && ./setup_agent_airgapped.sh
```

--------------------------------

### Install Instana Kubectl Plugin on Debian/Ubuntu

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=installing-instana-kubectl-plug-in

This snippet installs the Instana kubectl plug-in using apt on Debian or Ubuntu systems after the repository has been added. It first updates the package list and then installs the plugin.

```shell
apt update -y
apt install -y instana-kubectl-plugin
```

--------------------------------

### Start Instana Agent (Shell)

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=agents-installing-zos-unix-system-services-uss

Starts the Instana host agent by executing the start script located in the agent's bin directory. Replace INSTANA_AGENT_FOLDER with the actual installation path.

```shell
INSTANA_AGENT_FOLDER/bin/start
```

--------------------------------

### Instana Agent Setup and Metadata Example (Swift)

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=applications-ios-api

An example demonstrating how to set up the Instana agent with a key and reporting URL, and how to add custom metadata for 'Platform' and 'Environment'. This is typically done during the application's launch sequence.

```swift
func application (_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Instana.setup(key: InstanaKey, reportingURL: InstanaURL)
    Instana.setMeta(value: "ReactNative", key: "Platform")
    Instana.setMeta(value: "DEBUG", key: "Environment")
    return true
}
```

--------------------------------

### Instana Core Configuration Example (YAML)

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=installing-instana-backend

An example `config.yaml` file for Instana core configuration. It includes settings for Diffie-Hellman parameters, repository and sales keys, storage configurations (S3/GCS), service provider authentication, proxy settings, and email configurations (SMTP/SES).

```yaml
# Diffie-Hellman parameters to use
dhParams: |
  -----BEGIN DH PARAMETERS-----
  <snip/>
  -----END DH PARAMETERS-----
# The repository password for accessing the Instana agent repository.
# Use the download key that you received from us
repositoryPassword: mydownloadkey
# The sales key you received from us
salesKey: mysaleskey
# Seed for creating crypto tokens. Pick a random 12 char string
tokenSecret: mytokensecret
# Configuration for raw spans storage
storageConfigs:
  rawSpans:
    # Required if using S3 or compatible storage bucket.
    # Credentials should be configured.
    # Not required if IRSA on EKS is used.
    s3Config:
      accessKeyId: ...
      secretAccessKey: ...
    # Required if using Google Cloud Storage.
    # Credentials should be configured.
    # Not required if GKE with workload identity is used.
    gcloudConfig:
      serviceAccountKey: ...

# SAML/OIDC configuration
serviceProviderConfig:
  # Password for the key/cert file
  keyPassword: mykeypass
  # The combined key/cert file
  pem: |
    -----BEGIN RSA PRIVATE KEY-----
    <snip/>
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    <snip/>
    -----END CERTIFICATE-----
# Required if a proxy is configured that needs authentication
proxyConfig:
  # Proxy user
  user: myproxyuser
  # Proxy password
  password: my proxypassword
emailConfig:
  # Required if SMTP is used for sending e-mails and authentication is required
  smtpConfig:
    user: mysmtpuser
    password: mysmtppassword
  # Required if using for sending e-mail.
  # Credentials should be configured.
  # Not required if using IRSA on EKS.
  sesConfig:
  # The sesConfig configuration is mandatory when you use the Simple Email Service (SES) of Amazon for sending emails from the application. The sesConfig section includes two fields: accessKeyId and secretAccessKey, which are used to authenticate the application with Amazon SES allowing it to send emails on behalf of the specified AWS account.
    accessKeyId: ...
    secretAccessKey: ...
# Optional: You can add one or more custom CA certificates to the component trust stores

```

--------------------------------

### Instana REST API - Getting Started

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=api-getting-started

This section covers the prerequisites, generating API tokens for authentication, and how to make requests to the Instana REST API.

```APIDOC
## Instana REST API - Getting Started

### Description

The Instana REST API allows you to integrate Instana's monitoring and observability platform into your applications. This guide covers prerequisites, generating API tokens for authentication, and making authenticated requests.

### Prerequisites

*   Basic understanding of RESTful APIs and HTTP protocols.
*   An Instana account.

### Authentication

To authenticate requests, you need an API token generated from the Instana UI.

1.  Log in to your Instana account.
2.  Navigate to **Settings** > **Security & Access** > **API Tokens**.
3.  Create a new token, provide a name, and set appropriate permissions.
4.  Copy the generated API token and store it securely.

### Making Requests

Instana REST API uses standard HTTP methods. The base URL is specific to your Instana instance.

*   **Base URL:** `https://<TENANT>-<UNIT>.instana.io/api`
*   **Authorization Header:** `Authorization: Bearer <YOUR_API_TOKEN>`

### Request Example (cURL)

```bash
curl -X GET https://<TENANT>-<UNIT>.instana.io/api/<INSTANA_REST_API_ENDPOINT> \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

### Response Example (Success)

```json
{
  "example": "response body"
}
```

### Error Handling

Standard HTTP error codes will be returned for failed requests. Consult Instana documentation for specific error responses.
```

--------------------------------

### Start Instana Host Agent on UNIX

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=unix-installing-agent

Command to start the Instana host agent after installation on a UNIX system. Ensure you replace *instanaAgentDir* with the actual installation directory. This is a crucial step after extracting the agent archive.

```bash
*instanaAgentDir*/bin/start

```

--------------------------------

### Start Instana Agent in Background

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=agents-installing-mac-os

This command initiates the Instana agent to run in the background. Ensure the JAVA_HOME environment variable is correctly set before execution.

```shell
bin/start
```

--------------------------------

### Start Instana Database Containers

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=backend-installing-data-stores-as-docker-images

Starts all database containers for Instana. This command is used to bring the Instana datastore services back online after they have been stopped. No arguments are required.

```bash
instana datastores start
```

--------------------------------

### Start Instana Host Agent using .bat file (Windows)

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=windows-installing-agent

This snippet shows how to start the Instana host agent after manual installation using a .zip file on a Windows system. It assumes the agent has been extracted to a specified directory. No external dependencies are required beyond the extracted agent files and a compatible JVM.

```batch
<instana-agent-install-dir>\bin\start.bat

```

--------------------------------

### Start Instana Agent after Copy-Pasting Script (Shell)

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=agents-installing-zos-unix-system-services-uss

This command makes the agent installation script executable and then runs it to start the Instana agent. This is used when the script was copied and pasted directly into the z/OS-USS layer.

```shell
bash
chmod +x ./setup_agent_airgapped.sh && ./setup_agent_airgapped.sh
```

--------------------------------

### Verify Instana kubectl Plugin Installation

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=installing-instana-kubectl-plug-in

This command checks if the Instana kubectl plug-in has been successfully installed and is recognized by kubectl. It will display the version information of the plug-in if it's correctly installed.

```bash
kubectl-instana --version

```

--------------------------------

### Install Instana Console Package (Ubuntu/Debian)

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=backend-installing-data-stores-as-docker-images

This command updates the package list and installs the `instana-console` package, which is necessary for setting up the Docker-based data store. Ensure the repository is correctly configured before running this.

```shell
apt update -y
apt install -y instana-console

```

--------------------------------

### Run Instana OTel SDK Executable for Informix DB

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=technologies-monitoring-informix-db

Executes the Instana OpenTelemetry SDK for Informix DB from the command line. This starts the monitoring agent.

```bash
./bin/otel-dc-rdb
```

--------------------------------

### Install Single-Node Instana Cluster using stanctl

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=installing-standard-edition-in-online-environment

This command initiates the installation of a single-node Instana cluster. It requires no additional flags for basic setup. The command handles the creation of the cluster and the Instana backend installation.

```bash
stanctl up

```

--------------------------------

### Generate Instana YAML Templates with kubectl plug-in

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=installing-instana-backend

This command uses the Instana kubectl plug-in to generate YAML templates for namespaces and custom resources, aiding in the setup process for the Instana backend. Ensure the Instana kubectl plug-in is installed before execution.

```bash
kubectl instana template --output-dir <dir>
```

--------------------------------

### Starting the Instana Host Agent (CL Command)

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=agents-installing-i

This CL command starts the Instana host agent on an IBM i system. It requires the path to the Java home directory and the agent installation directory. The agent needs to run with *ALLOBJ authority.

```cl
SBMJOB CMD(QSH CMD('export JAVA_HOME=<java-home>; exec bash *instanaAgentDir*/bin/start')) JOBQ(QUSRNOMAX) LOG(*JOBD *JOBD *NOLIST)

```

--------------------------------

### Set up Kubernetes with Minikube

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=kubernetes-installing-agent

Configures a local Kubernetes cluster using Minikube. This involves adding the Kubernetes repository, installing kubectl, downloading and installing the Minikube RPM, starting the cluster with Docker driver, and setting up the Docker environment for Minikube.

```bash
cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/v1.28/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/v1.28/rpm/repodata/repomd.xml.key
exclude=kubelet kubeadm kubectl cri-tools kubernetes-cni
EOF

```

```bash
sudo yum install -y kubectl

```

```bash
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-latest.x86_64.rpm

```

```bash
sudo rpm -Uvh minikube-latest.x86_64.rpm

```

```bash
minikube start --force --driver=docker

```

```bash
eval $(minikube docker-env)

```

```bash
kubectl cluster-info

```

--------------------------------

### Install Instana Console (Bash)

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=backend-installing-data-stores-as-docker-images

These commands install the `instana-console` package on a Red Hat/CentOS system. It first clears the yum cache, then updates the package list, and finally installs the `instana-console` package. Ensure the Instana repository is added before running these commands.

```bash
yum clean expire-cache -y
yum update -y
yum install -y instana-console
```

--------------------------------

### Install Instana AWS Agent on EC2 (Bash)

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=agents-amazon-web-services-aws

This script downloads and executes the Instana AWS agent setup. It requires the agent key and location as parameters. Ensure you have `curl` installed on your EC2 instance.

```bash
#!/bin/bash

curl -o setup_agent.sh https://setup.instana.io/agent
chmod 700 ./setup_agent.sh
sudo ./setup_agent.sh -y -a <your-agent-key> -m aws -t dynamic -e <location> -s

```

--------------------------------

### Instana REST API

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=api-authenticating-instana-rest

Documentation for the Instana REST API, including getting started, pagination, rate limits, filtering, authentication, and examples.

```APIDOC
## Instana REST API

### Description
This section covers the Instana REST API, detailing how to interact with Instana's observability data programmatically. It includes guides on initial setup, handling large datasets with pagination, understanding API usage limits through rate limits, applying filters to retrieve specific data, and secure authentication methods.

### Method
All methods (GET, POST, PUT, DELETE, etc.) are applicable depending on the specific operation.

### Endpoint
`/api/v1/...` (specific endpoints vary)

### Parameters

#### Path Parameters
None explicitly defined for the general API, but specific endpoints may have them.

#### Query Parameters
- **limit** (integer) - Optional - Maximum number of results to return.
- **offset** (integer) - Optional - Number of results to skip.
- **filter** (string) - Optional - Criteria to filter the results.

#### Request Body
Request bodies vary depending on the endpoint and operation (e.g., for creating or updating resources).

### Request Example
```json
{
  "example": "POST /api/v1/some-resource { \"field\": \"value\" }"
}
```

### Response
#### Success Response (200)
- **data** (array/object) - The requested data or result of the operation.
- **pagination** (object) - Information about pagination (e.g., total items, next/previous links).

#### Response Example
```json
{
  "example": "{\n  \"data\": [ { \"id\": \"123\", \"name\": \"Example Item\" } ],\n  \"pagination\": { \"total\": 100, \"limit\": 10, \"offset\": 0 }\n}"
}
```
```

--------------------------------

### Example `config.yaml` for Instana Observability

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=operators-verifying-configuration

This YAML configuration defines connection parameters for multiple data stores used in Instana observability. It includes fields for usernames and passwords, with placeholders for secrets that need to be retrieved during installation. Ensure all sensitive information is handled securely.

```yaml
datastoreConfigs:
  kafkaConfig:
    adminUser: strimzi-kafka-user
    adminPassword: <RETRIEVED_FROM_SECRET>
    consumerUser: strimzi-kafka-user
    consumerPassword: <RETRIEVED_FROM_SECRET>
    producerUser: strimzi-kafka-user
    producerPassword: <RETRIEVED_FROM_SECRET>
  elasticsearchConfig:
    adminUser: elastic
    adminPassword: <RETRIEVED_FROM_SECRET>
    user: elastic
    password: <RETRIEVED_FROM_SECRET>
  postgresConfigs:
    - user: postgres
      password: <RETRIEVED_FROM_SECRET>
      adminUser: postgres
      adminPassword: <RETRIEVED_FROM_SECRET>
  cassandraConfigs:
    - user: instana-superuser
      password: <RETRIEVED_FROM_SECRET>
      adminUser: instana-superuser
      adminPassword: <RETRIEVED_FROM_SECRET>
  clickhouseConfigs:
    - user: clickhouse-user
      password: <USER_GENERATED_PASSWORD>
      adminUser: clickhouse-user
      adminPassword: <USER_GENERATED_PASSWORD>
```

--------------------------------

### Start Milvus Service with Docker Compose

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=databases-milvus

This command starts the Milvus service using the downloaded Docker Compose file. It requires `docker compose` (or `docker-compose`) to be installed and accessible. The `-d` flag runs the containers in detached mode.

```bash
sudo docker compose up -d
```

--------------------------------

### Instana kubectl Plug-in Help Command - Shell

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=installing-instana-kubectl-plug-in

This command displays the default help information for the Instana kubectl plug-in. It lists available commands and general usage instructions. No specific inputs are required other than the flag itself.

```shell
kubectl-instana --help
```

--------------------------------

### Example Output for CNPG Postgres Operator Verification

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=i-postgres-1

This is an example output of the `kubectl get all -n instana-postgres` command, showing the status of pods, services, and deployments when using the CloudNativePG (CNPG) operator.

```text
NAME                                      READY    STATUS    RESTARTS    AGE
pod/postgres-1                             1/1     Running     0         100s
pod/postgres-2                             1/1     Running     0         69s
pod/postgres-3                             1/1     Running     0         41s
pod/cnpg-cloudnative-pg-64bbc87958-fqnrl   1/1     Running     0         11m

NAME                           TYPE        CLUSTER-IP       EXTERNAL-IP   PORT
service/cnpg-webhook-service   ClusterIP   172.30.66.183    <none>        443/TCP
service/postgres-r             ClusterIP   172.30.163.146   <none>        5432/TCP
service/postgres-ro            ClusterIP   172.30.226.75    <none>        5432/TCP
service/postgres-rw            ClusterIP   172.30.235.178   <none>        5432/TCP

NAME                                READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/cnpg-cloudnative-p   1/1     1            1           11m

NAME                                           DESIRED   CURRENT   READY   AGE
replicaset.apps/cnpg-cloudnative-pg-64bbc87958   1         1         1       11m
```

--------------------------------

### Build OpenTelemetry gRPC Example with CMake (Windows)

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=sdks-c

This snippet demonstrates how to configure and build the OpenTelemetry gRPC example on Windows using CMake. It utilizes Vcpkg for managing dependencies and specifies the path to the toolchain file. The output is an executable named 'otel_grpc_sample'.

```cmake
add_executable(otel_grpc_sample grpc_main.cc
    "foo_library/foo_library.cc"
)

target_link_libraries(otel_grpc_sample 
    ${OTEL_LIBS_PATH}/opentelemetry_proto.lib
    ${OTEL_LIBS_PATH}/opentelemetry_proto_grpc.lib
    ${OTEL_LIBS_PATH}/opentelemetry_exporter_otlp_grpc.lib
    ${OTEL_LIBS_PATH}/opentelemetry_exporter_otlp_grpc_client.lib
    ${OTEL_LIBS_PATH}/opentelemetry_logs.lib
    ${OTEL_LIBS_PATH}/opentelemetry_otlp_recordable.lib
    ${OTEL_LIBS_PATH}/opentelemetry_common.lib
    ${OTEL_LIBS_PATH}/opentelemetry_trace.lib
    ${OTEL_LIBS_PATH}/opentelemetry_resources.lib
)
target_link_libraries(otel_grpc_sample absl::flat_hash_map absl::strings absl::str_format)
target_link_libraries(otel_grpc_sample gRPC::gpr gRPC::grpc gRPC::grpc++ gRPC::grpc++_alts)
```

```bat
cd otlp
mkdir build
cd .\build\
crape .. -DCMAKE_TOOLCHAIN_FILE="<path to vcpkg>/scripts/buildsystems/vcpkg.cmake"
crape --build .

```

--------------------------------

### Example ClickHouse Operator Deployment Output

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=i-clickhouse-1

This is an example output from the `kubectl get all -n instana-clickhouse` command, illustrating a successful ClickHouse operator deployment. It shows the status of pods, services, deployments, and stateful sets, all indicating a 'Running' state.

```text
NAME                                                                  READY   STATUS    RESTARTS   AGE
pod/chi-instana-local-0-0-0                                           2/2     Running   0          8m46s
pod/chi-instana-local-0-1-0                                           2/2     Running   0          8m5s
pod/clickhouse-operator-altinity-clickhouse-operator-86b5f9b57689rr   2/2     Running   0          70m
pod/instana-zookeeper-0                                               1/1     Running   0          4h3m
pod/instana-zookeeper-1                                               1/1     Running   0          4h2m
pod/instana-zookeeper-2                                               1/1     Running   0          4h2m

NAME                                                              TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)                                        AGE
service/chi-instana-local-0-0                                      ClusterIP      None            <none>          9000/TCP,8123/TCP,9009/TCP                     8m16s
service/chi-instana-local-0-1                                      ClusterIP      None            <none>          9000/TCP,8123/TCP,9009/TCP                     7m35s
service/clickhouse-instana                                         LoadBalancer   192.168.1.167   35.246.237.19   8123:32714/TCP,9000:31317/TCP                  8m11s
service/clickhouse-operator-altinity-clickhouse-operator-metrics   ClusterIP      192.168.1.136   <none>          8888/TCP                                       70m
service/instana-zookeeper-admin-server                             ClusterIP      192.168.1.126   <none>          8080/TCP                                       4h3m
service/instana-zookeeper-client                                   ClusterIP      192.168.1.13    <none>          2181/TCP                                       4h3m
service/instana-zookeeper-headless                                 ClusterIP      None            <none>          2181/TCP,2888/TCP,3888/TCP,7000/TCP,8080/TCP   4h3m

NAME                                                              READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/clickhouse-operator-altinity-clickhouse-operator   1/1     1            1           70m

NAME                                                                          DESIRED   CURRENT   READY   AGE
replicaset.apps/clickhouse-operator-altinity-clickhouse-operator-86b5f9b579   1         1         1       70m

NAME                                     READY   AGE
statefulset.apps/chi-instana-local-0-0   1/1     8m50s
statefulset.apps/chi-instana-local-0-1   1/1     8m9s
statefulset.apps/instana-zookeeper       3/3     4h3m
```

--------------------------------

### Clone and Navigate OpenTelemetry Demo Repository

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=applications-monitoring-net-from-opentelemetry-demo-instana

This snippet demonstrates how to clone the OpenTelemetry Demo repository and navigate into its root directory using Git and the command line. This is a foundational step for setting up the demo environment.

```bash
git clone https://github.com/open-telemetry/opentelemetry-demo.git
cd opentelemetry-demo/

```

--------------------------------

### Initialize Instana Backend

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=ice-installing-1

This command initializes the Instana backend installation. It requires root privileges and generates a `settings.hcl` file in the current directory. The user will then be prompted to provide tenant name, agent key, sales key, DNS name, and certificate paths.

```shell
instana init
```

--------------------------------

### Import Optional Node.js Module

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=monitoring-using-api-scripts

This example shows the standard Node.js procedure for importing an optional module, specifically using `require('crypto-js')` in this case. Ensure the module is installed in your environment.

```javascript
const crypto = require('crypto-js');
```

--------------------------------

### Example Output for Zalando Postgres Operator Verification

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=i-postgres-1

This is an example output of the `kubectl get all -n instana-postgres` command, showing the status of pods, services, deployments, replicasets, statefulsets, operator configurations, and postgresql resources when using the Zalando operator.

```text
NAME                                     READY   STATUS    RESTARTS   AGE
pod/postgres-0                           1/1     Running   0          100s
pod/postgres-1                           1/1     Running   0          69s
pod/postgres-2                           1/1     Running   0          41s
pod/postgres-operator-766455c58c-ntmpf   1/1     Running   0          11m

NAME                        TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/postgres            ClusterIP   192.168.1.107   <none>        5432/TCP   101s
service/postgres-operator   ClusterIP   192.168.1.35    <none>        8080/TCP   11m
service/postgres-repl       ClusterIP   192.168.1.72    <none>        5432/TCP   101s

NAME                                READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/postgres-operator   1/1     1            1           11m

NAME                                           DESIRED   CURRENT   READY   AGE
replicaset.apps/postgres-operator-766455c58c   1         1         1       11m

NAME                        READY   AGE
statefulset.apps/postgres   3/3     103s

NAME                                                    IMAGE                             CLUSTER-LABEL   SERVICE-ACCOUNT   MIN-INSTANCES   AGE
operatorconfiguration.acid.zalan.do/postgres-operator   ghcr.io/zalando/spilo-15:3.0-p1   cluster-name    postgres-pod      -1              11m

NAME                                TEAM      VERSION   PODS   VOLUME   CPU-REQUEST   MEMORY-REQUEST   AGE    STATUS
postgresql.acid.zalan.do/postgres   instana   15        3      10Gi     500m          2Gi              106s   Running
```

--------------------------------

### Download Instana License using kubectl Plugin

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=installing-instana-backend

Downloads the Instana license file using the Instana kubectl plugin. This command requires your SalesKey to generate the appropriate license for activation.

```bash
kubectl instana license download --sales-key <SalesKey>

```

--------------------------------

### Install Instana Backend

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=edition-backing-up-restoring

Command to install the Instana backend and data stores on the new host. This command utilizes existing configurations from the `$HOME/.stanctl/instana.yaml` file.

```bash
stanctl up
```

--------------------------------

### Configure Basic Data Store Connections

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=installing-instana-backend

Sets up basic connection configurations for various data stores (Cassandra, ClickHouse, PostgreSQL, Elasticsearch, Kafka) in Instana Core. Requires at least the hosts to be configured.

```yaml
spec:
  datastoreConfigs:
    cassandraConfigs:
      - hosts:
          - <IP address or hostname>
    clickhouseConfigs:
      - hosts:
          - <IP address or hostname>
    postgresConfigs:
      - hosts:
          - <IP address or hostname>
    elasticsearchConfig:
      hosts:
        - <IP address or hostname>
    kafkaConfig:
      hosts:
        - <IP address or hostname>
```

--------------------------------

### Instana Node.js Collector for Apigee Microgateway

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=technologies-monitoring-apigee-microgateway

Integrates Instana's Node.js collector with Apigee Microgateway, starting from version @instana/collector@1.89.0. This integration requires specific setup steps when Microgateway is installed globally.

```bash
# Ensure Instana collector is installed (if not already)
# npm install @instana/collector

# Example of starting edgemicro with the collector
# This assumes you have edgemicro installed globally
# EDGECZAR_LOG_LEVEL=info EDGEMICRO_KEY=YOUR_API_KEY EDGEMICRO_ORG=YOUR_ORG_ID EDGEMICRO_HOST=YOUR_APIGEE_HOST node $(npm root -g)/@instana/collector/lib/instrument.js $(which edgemicro) start

# Or if using forever
# EDGECZAR_LOG_LEVEL=info EDGEMICRO_KEY=YOUR_API_KEY EDGEMICRO_ORG=YOUR_ORG_ID EDGEMICRO_HOST=YOUR_APIGEE_HOST node $(npm root -g)/@instana/collector/lib/instrument.js $(which edgemicro) forever -a start
```

--------------------------------

### Send GET HTTP Request with $got

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=monitoring-using-api-scripts

This JavaScript example shows how to send an HTTP GET request using the $got library. It configures request options, including the URL and SSL rejection policy, and then sends the request. The snippet includes validation of the response status code to ensure the request was successful (expecting 200).

```javascript
const assert = require('assert');
(async function () {
    var options = {
      url: 'https://reqres.in/api/messages',
      https:{ rejectUnauthorized: false }
    };

    // Send GET request
    let response = await $got.get(options);

    // Validate the response status code, it should be 200 here
    assert.ok(response && response.statusCode == 200, 'Expect 200');
})();
```

--------------------------------

### Add Instana Repository for Debian/Ubuntu

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=installing-instana-kubectl-plug-in

This snippet adds the Instana package repository to Debian or Ubuntu systems. It requires a download key and configures apt sources and authentication. Ensure the download key is replaced with your actual key.

```shell
export DOWNLOAD_KEY="<download_key>"

echo 'deb [signed-by=/usr/share/keyrings/instana-archive-keyring.gpg] https://artifact-public.instana.io/artifactory/rel-debian-public-virtual generic main' > /etc/apt/sources.list.d/instana-product.list

cat << EOF > /etc/apt/auth.conf
machine artifact-public.instana.io
  login _
  password $DOWNLOAD_KEY
EOF

wget -nv -O- --user=_ --password="$DOWNLOAD_KEY" https://artifact-public.instana.io/artifactory/api/security/keypair/public/repositories/rel-debian-public-virtual | gpg --dearmor > /usr/share/keyrings/instana-archive-keyring.gpg
```

--------------------------------

### ClickHouseInstallation CR - Full Resource Definition

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=i-clickhouse

This provides a complete example of the ClickHouseInstallation Custom Resource definition, including storage configuration, cluster settings, ZooKeeper integration, profiles, quotas, and user configurations.

```APIDOC
## ClickHouseInstallation CR - Full Resource Definition

### Description
This provides a complete example of the ClickHouseInstallation Custom Resource definition, including storage configuration, cluster settings, ZooKeeper integration, profiles, quotas, and user configurations.

### Method
N/A (Configuration file)

### Endpoint
N/A (Configuration file)

### Parameters
#### Request Body
- **apiVersion** (string) - Specifies the API version for the ClickHouseInstallation resource (e.g., "clickhouse.altinity.com/v1").
- **kind** (string) - Specifies the resource kind as "ClickHouseInstallation".
- **metadata.name** (string) - The name of the ClickHouseInstallation resource (e.g., "instana").
- **spec.defaults.templates** (object) - Default templates for volumes and services.
  - **dataVolumeClaimTemplate** (string) - Name of the data volume claim template.
  - **logVolumeClaimTemplate** (string) - Name of the log volume claim template.
  - **serviceTemplate** (string) - Name of the service template.
- **spec.configuration.files** (object) - Custom configuration files for ClickHouse.
  - **config.d/storage.xml** (string) - XML content for storage configuration.
- **spec.configuration.clusters** (array) - Configuration for ClickHouse clusters.
  - **name** (string) - Name of the cluster (e.g., "local").
  - **templates.podTemplate** (string) - Name of the pod template.
  - **layout.shardsCount** (integer) - Number of shards.
  - **layout.replicasCount** (integer) - Number of replicas per shard.
  - **schemaPolicy.replica** (string) - Schema replication policy.
  - **schemaPolicy.shard** (string) - Schema shard policy.
- **spec.configuration.zookeeper.nodes** (array) - List of ZooKeeper nodes.
  - **host** (string) - Hostname of a ZooKeeper node.
- **spec.configuration.profiles** (object) - ClickHouse profiles configuration.
- **spec.configuration.quotas** (object) - ClickHouse quotas configuration.
- **spec.configuration.settings** (object) - ClickHouse server settings.
- **spec.configuration.users** (object) - ClickHouse users configuration.
  - **default/password** (string) - Default password for the 'default' user.
  - **clickhouse-user/networks/ip** (string) - Allowed IP networks for 'clickhouse-user'.
  - **clickhouse-user/password** (string) - Plain text password for 'clickhouse-user'.
  - **clickhouse-user/password_sha256_hex** (string) - SHA256 hex hash of the password for 'clickhouse-user'.
  - **clickhouse-user/password_double_sha1_hex** (string) - Double SHA1 hex hash of the password for 'clickhouse-user'.

### Request Example
```yaml
apiVersion: "clickhouse.altinity.com/v1"
kind: "ClickHouseInstallation"
metadata:
  name: "instana"
spec:
  defaults:
    templates:
      dataVolumeClaimTemplate: instana-clickhouse-data-volume
      logVolumeClaimTemplate: instana-clickhouse-log-volume
      serviceTemplate: service-template
  configuration:
    files:
      config.d/storage.xml: |
        <clickhouse>
          <storage_configuration>
            <disks>
              <default/>
              <cold_disk>
                <path>/var/lib/clickhouse-cold/</path>
              </cold_disk>
            </disks>
            <policies>
              <logs_policy>
                <volumes>
                  <data>
                    <disk>default</disk>
                  </data>
                  <cold>
                    <disk>cold_disk</disk>
                  </cold>
                </volumes>
              </logs_policy>
              <logs_policy_v4>
                <volumes>
                  <tier1>
                    <disk>default</disk>
                  </tier1>
                  <tier2>
                    <disk>cold_disk</disk>
                  </tier2>
                </volumes>
              </logs_policy_v4>
            </policies>
          </storage_configuration>
        </clickhouse>
    clusters:
      - name: local
        templates:
          podTemplate: clickhouse
        layout:
          shardsCount: 1
          replicasCount: 2 # The replication count of 2 is fixed for Instana backend installations
        schemaPolicy:
          replica: None
          shard: None
    zookeeper:
      nodes:
        - host: instana-zookeeper-headless.instana-clickhouse
    profiles:
      default/prefer_localhost_replica: 1
      default/max_memory_usage: 10000000000 # If memory limits are set, this value must be adjusted according to the limits.
      default/joined_subquery_requires_alias: 0
      default/max_execution_time: 100
      default/max_query_size: 1048576
      default/use_uncompressed_cache: 0
      default/enable_http_compression: 1
      default/load_balancing: random
      default/background_pool_size: 32
      default/background_schedule_pool_size: 32
      default/distributed_directory_monitor_split_batch_on_failure: 1
      default/distributed_directory_monitor_batch_inserts: 1
      default/insert_distributed_sync: 1
      default/log_queries: 1
      default/log_query_views: 1
      default/max_threads: 16
      default/allow_experimental_database_replicated: 1
    quotas:
      default/interval/duration: 3600
      default/interval/queries: 0
      default/interval/errors: 0
      default/interval/result_rows: 0
      default/interval/read_rows: 0
      default/interval/execution_time: 0
    settings:
      remote_servers/all-sharded/secret: clickhouse-default-pass
      remote_servers/all-replicated/secret: clickhouse-default-pass
      remote_servers/local/secret: clickhouse-default-pass
      max_concurrent_queries: 200
      max_table_size_to_drop: 0
      max_partition_size_to_drop: 0
    users:
      default/password: "clickhouse-default-pass"
      clickhouse-user/networks/ip: "::/0"
      clickhouse-user/password: "clickhouse-pass"
      # Or
      # Generate password and the corresponding SHA256 hash with:
      # $ PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha256sum | tr -d '-'
      # 6edvj2+d                                  #  <- first line is the password
      # a927723f4a42cccc50053e81bab1fcf579d8d8fb54a3ce559d42eb75a9118d65  # <- second line is the corresponding SHA256 hash
      # clickhouse-user/password_sha256_hex: "a927723f4a42cccc50053e81bab1fcf579d8d8fb54a3ce559d42eb75a9118d65"
      # Or
      # Generate password and the corresponding SHA1 hash with:
      # $ PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'
      # LJfoOfxl                                  # <- first line is the password, put this in the k8s secret
      # 3435258e803cefaab7db2201d04bf50d439f6c7f  # <- the corresponding double SHA1 hash, put this below
```

### Response
N/A (Configuration is applied during deployment)

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Install Kafka Operator and Data Store on Linux on IBM Z/LinuxONE

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=i-kafka

This section details the installation of the Kafka operator and the setup of the Kafka data store on Linux on IBM Z and LinuxONE. It specifies the required operator and image versions for deployment, ensuring compatibility with Strimzi versions and Kafka deployments. It also references a guide for migrating from ZooKeeper to KRaft.

```text
Platform| Operator versions| Helm chart version| Image with tag  
---|---|---|---  
Linux® on IBM Z® and LinuxONE| 0.47.0| 0.47.0| artifact-public.instana.io/self-hosted-images/3rd-party/operator/strimzi:0.47.0_v0.22.0  
  
artifact-public.instana.io/self-hosted-images/3rd-party/datastore/kafka:0.47.0-kafka-3.9.1_v0.23.0  
```

--------------------------------

### Run OTel Data Collector for GenAI

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=started-install-otel-data-collector-genai-odcg

Starts the OTel Data Collector for GenAI in the background using `nohup`. Redirects standard output and error to `/dev/null` to prevent console clutter.

```shell
nohup ./bin/otel-dc-genai >/dev/null 2>&1 &

```

--------------------------------

### Initialize Instana Datastores with Settings

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=backend-installing-data-stores-as-docker-images

Initializes the Instana datastores using a specified HCL settings file. This command is crucial for the initial setup of the host's database configuration. It requires the path to the database settings file as an argument.

```bash
instana datastores init -f /path/to/db-settings.hcl
```

--------------------------------

### Install Instana Kubectl Plugin on RHEL/CentOS

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=installing-instana-kubectl-plug-in

This snippet installs the Instana kubectl plug-in using yum on RHEL or CentOS systems. It cleans the cache, updates packages, and then installs the plugin.

```shell
yum clean expire-cache -y
yum update -y
yum install -y instana-kubectl-plugin
```

--------------------------------

### Create Instana Air-Gapped Installation Package

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=installing-standard-edition-in-air-gapped-environment

This command initiates the creation of an air-gapped installation package for Instana. It requires the `stanctl` tool to be installed. The output directory can be specified using `--output-dir`. Users will be prompted to enter download and sales keys, and to select an Instana version.

```bash
stanctl air-gapped package

```

--------------------------------

### Install Groq Dependencies

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=platforms-groq

Installs the necessary Groq Python library. This is a prerequisite for interacting with the Groq API. No specific inputs or outputs are defined beyond the successful installation of the package.

```bash
pip3 install groq==0.13.1
```

--------------------------------

### Verify IDOT Installation in OpenShift

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=collector-installing-instana-distribution-opentelemetry-kubernetes

Checks the status of the deployed IDOT pods within the current OpenShift project or a specified namespace. It can be performed using `oc get pods` or `kubectl get pods`.

```bash
oc get pods

```

```bash
kubectl get pods -n instana-collector

```

--------------------------------

### Write REST API Test Cases with GET and POST Requests

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=monitoring-using-api-scripts

This JavaScript code provides an example of writing a REST API test case using the $got library for HTTP requests and the assert module for validation. It shows how to send GET and POST requests, and then assert on the status code and response body content. The code handles JSON payloads for POST requests and includes basic error checking.

```javascript
const assert = require('assert');

(async function () {
    // GET example
    const {statusCode} = await $got.get('https://httpbin.org/get');
    assert.equal(statusCode, 200, 'Expected a 200 Status Code, current is ' + statusCode);

    // POST example
    var postOptions = {
      url: 'https://httpbin.org/post',
      json: {
        'name': 'TestName',
        'type': 'Synthetic Script'
      },
      https:{ rejectUnauthorized: false },
      headers:{'accept': 'application/json'}
    };

    let postResponse = await $got.post(postOptions);
    assert.ok(postResponse.statusCode == 200, 'POST status is ' + postResponse.statusCode + ', it should be 200');

    const jsonBody = JSON.parse(postResponse.body);
    assert.equal(jsonBody.json.name, 'TestName', 'Expected TestName');
    assert.equal(jsonBody.json.type, 'Synthetic Script', 'Expected Synthetic Script');
})();
```

--------------------------------

### Add Instana Repository and Authentication (Ubuntu/Debian)

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=backend-installing-data-stores-as-docker-images

These commands add the Instana repository to your system's sources list and configure authentication using a provided download key. This is a prerequisite for installing Instana packages via apt.

```shell
export DOWNLOAD_KEY="<download_key>"

echo 'deb [signed-by=/usr/share/keyrings/instana-archive-keyring.gpg] https://artifact-public.instana.io/artifactory/rel-debian-public-virtual generic main' > /etc/apt/sources.list.d/instana-product.list

cat << EOF > /etc/apt/auth.conf
machine artifact-public.instana.io
  login _
  password $DOWNLOAD_KEY
EOF

wget -nv -O- --user=_ --password="$DOWNLOAD_KEY" https://artifact-public.instana.io/artifactory/api/security/keypair/public/repositories/rel-debian-public-virtual | gpg --dearmor > /usr/share/keyrings/instana-archive-keyring.gpg

```

--------------------------------

### Download Instana License

Source: https://www.ibm.com/docs/en/instana-observability/1.0.305/index_topic=installing-instana-aro

Downloads the Instana license using a provided sales key. This is a crucial step before installing the Instana backend.

```bash
kubectl instana license download --sales-key <redacted>

```