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-FQDN-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 with dedicated 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 with dedicated 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

Data Retention for Infrastructure and Platform monitoring

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 {
  metric_roll_up_5     = "86400"
  metric_roll_up_60    = "2678400"
  metric_roll_up_300   = "8035200"
  metric_roll_up_3600  = "0"
}
Retention Description Type
metric_roll_up_5 Duration (in seconds) that 5-second-rollups are available. int
metric_roll_up_60 Duration (in seconds) that 1-minute-rollups are available. int
metric_roll_up_300 Duration (in seconds) that 5-minute-rollups are available. int
metric_roll_up_3600 Duration (in seconds) that 1-hour-rollups are available. int

Data Retention for Application Perspectives and End User Monitoring

Application Perspectives and End User Monitoring share the same data retention parameter:

retention {
  app_data_short_term  = "7"
}
Retention Description Type
app_data_short_term Days of retention. int

Changing app_data_short_term has an effect on new Application Perspectives data only.

Examples:

  • app_data_short_term is changed from 7 days to 14 days: old data will be deleted once it is older than 7 days, while new data will be deleted once it is older than 14 days.
  • app_data_short_term is changed from 14 days to 7 days: old data will be deleted once it is older than 14 days, while new data will be deleted once it is older than 7 days.

Changing app_data_short_term has an immediate effect on old and new End User Monitoring data.

Examples:

  • app_data_short_term is changed from 7 days to 14 days: old and new data is deleted once it is 14 days old.
  • app_data_short_term is changed from 14 days to 7 days: old and new data is deleted once it is 7 days old.

Beyond the retention period, a subset of the data is kept for 13 months.

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>"