Configuration (settings.hcl)

To Create a Template for the settings.hcl File

The settings.hcl file is generated during the installation process.

If required, run instana settings template to create a settings.hcl file with default (empty) values.

Default Configuration

The values for the following parameters are populated during the installation.

type      = "single"
profile   = "normal"
tenant    = "<Your-tenancy-identifier>"
unit      = "<Your-backend-identifier>"
agent_key = "<Your-agent-key>"
sales_key = "<Your-sales-key>"
host_name = "<The-hostname-of-the-machine-the-backend-is-installed-on>"
token_secret = "<max_12_digits>"

cert {
  crt     = "<Path-to-your-signed-certificate>"
  key     = "<Path-to-your-private-key-file>"
}

Data Directories

Instana defaults to the following directory structures.

dir {
  metrics  = "/mnt/metrics"
  traces   = "/mnt/traces"
  data     = "/mnt/data"
  logs     = "/var/log/instana"
}
Directory Description Type
Metrics The parent directory of where Cassandra creates its data directory. We recommend to put this on a high IO device on it's own disks (/mnt/metrics). string
Traces The parent directory of where Clickhouse creates its data directory. We recommend to put this on a high IO device on it's own disks (/mnt/traces). string
Data The parent directory of where Instana and third party components store data. string
Logs The parent directory of where all the components in our stack create log files. string

Data Retention

The following data retention parameters are calculated during the installation. A value of zero tells the system to not drop rollups of this time span. A zero value for smaller rollups can cause the disks to quickly fill up.

retention {
  rollup5     = "86400"
  rollup60    = "2678400"
  rollup300   = "8035200"
  rollup3600  = "0"
  app_data_short_term  = "7"
}
Retention Description Type
rollup5 Duration (in seconds) that 5-second-rollups are available. int
rollup60 Duration (in seconds) that 1-minute-rollups are available. int
rollup300 Duration (in seconds) that 5-minute-rollups are available. int
rollup3600 Duration (in seconds) that 1-hour-rollups are available. int
app_data_short_term Days of retention for all data. Change is effective only on new data (apart from website and mobile apps which are affected immediately). int

Notifications Server Settings

email {

  smtp {
    from      = "[email protected]"
    host      = "relay-1.acme.internal"      
    port      = "25"             
    user      = "[email protected]"        
    password  = "yUnoEm41l"        
    use_ssl   = "true"          
    start_tls = "false"          
  }
}
Parameter Description Type
from Sender email address from our notification emails. string
host SMTP server address or hostname that sends our notification emails. string
port Port of the SMTP server that sends our notification emails. int
user Username for the SMTP server that sends our notification emails. string
password Password for the SMTP server that sends our notification emails. string
use_ssl Indicates whether the SMTP server that sends our notification emails is spoken to via SSL. bool
start_tls Indicates whether the SMTP server that sends our notification emails is spoken to via SSL. bool

Proxy Settings

proxy {
  host     = "10.9.4.13"    
  port     = "8080"         
  user     = "anonymous"    
  password = "P4ssword1234"
}
Parameter Description Type
host If your backend server communicates with the cluster-external internet via a proxy server, this is either the address or hostname. string
port Port for the proxy server to speak to. int
user Username for the proxy server. int
password Password for the proxy server. string

Docker repository settings

docker_repository {
  base_url = "my.mirror.internal/v2/containers.instana.io"
  username = "user"
  password = "pass"
}
Parameter Description Type
base_url Base URL for the mirror repository, depending on your tag. string
username Username for the repository server. string
password Password for the repository server. string

OAuth settings

o_auth {
  client_id     = "123456-1n574n4adgjlmnop.apps.googleusercontent.com"
  client_secret = "XNLV-fpf_deadBeEf1234"      
}
Parameter Description Type
client_id Client ID for the Google oauth credential. string
client_secret Client secret password for the Google oauth credential. string

End-User Monitoring (EUM) settings

eum {
  tracking_base_url     = "https://mobile.acmecorp.com/eum/"  
}
Parameter Description Type
tracking_base_url URL under which the end-user monitoring ingestion endpoint is published, i.e. the eum-acceptor component. This configuration has no impact on data ingestion or processing. Instead it is used to present correct JavaScript and mobile app agent installations intructions within the Instana user interface. string
nginx_config Deprecated: Please do not use this configuration option. If you are using it, please stop doing so and instead deploy a separate reverse proxy on another machine. Refer to the dedicated Self-Hosted/On-Premise End-User Monitoring documentation to learn more. string

Generating REST API clients

The URL to the local open API specification is https://{onpremhost}/docs/openapi (since on-prem release 170). For detailed information on how to configure rest API clients, see our Web REST API docs.

Enabling audit logging

To configure an audit logger that logs each login to the Instana system. The following config toggle must be activated at root level in settings.hcl. Then the system must be updated by instana update -f /path/to/settings.hcl. The new log file can be found under the following path in the log directory /instana/butler/audit.log.

toggle "config.audit.log.level" {
  value = "info"
} 

Replacing existing certificates

To replace existing certificates with other certificates, in the settings.hcl file update paths to your certificate files. Then the system must be updated by instana update -f /path/to/settings.hcl.

cert {
  crt = "/mnt/cert/tls.crt"
  key = "/mnt/cert/tls.key"
}

Custom certificates for Webhook or Mail integrarions

To configure your Instana installation to successfully send data to Webhook with a custom certificate you can provide a custom java keystore (jssecacerts) that contains your certificate for our JVMs.

  1. Just copy a current jvm keystore from your JVM $JAVA_HOME/lib/security/cacerts
  2. Import your custom cert into this keystore, by using the jvm keytool with following command: $JAVA_HOME/bin/keytool -importcert -file custom-crt.crt -alias instana.com -keystore cacerts -storepass changeit
  3. Now you have to add the absolute path of the keystore with the configuration key custom_keystore into the settings.hcl.

    custom_keystore="<path_to_javakeystore>"