Supported Agent Configuration Options

Below is the full list of supported configurations you can set to customize the agent behavior, please take some time to read the descriptions for what they can achieve.

Usage: (Pass in intrusive setup)

from skywalking import config, agent
config.init(YourConfiguration=YourValue))
agent.start()

Usage: (Pass by environment variables)

export SW_AGENT_YourConfiguration=YourValue

Agent Core Configuration Options

Configuration Environment Variable Type Default Value Description
agent_collector_backend_services SW_AGENT_COLLECTOR_BACKEND_SERVICES <class ‘str’> oap_host:oap_port The backend OAP server address, 11800 is default OAP gRPC port, 12800 is HTTP, Kafka ignores this option and uses kafka_bootstrap_servers option. This option should be changed accordingly with selected protocol
agent_protocol SW_AGENT_PROTOCOL <class ‘str’> grpc The protocol to communicate with the backend OAP, http, grpc or kafka, we highly suggest using grpc in production as it’s well optimized than http. The kafka protocol provides an alternative way to submit data to the backend.
agent_name SW_AGENT_NAME <class ‘str’> Python Service Name The name of your awesome Python service
agent_instance_name SW_AGENT_INSTANCE_NAME <class ‘str’> str(uuid.uuid1()).replace('-', ‘') The name of this particular awesome Python service instance
agent_namespace SW_AGENT_NAMESPACE <class ‘str’> The agent namespace of the Python service (available as tag and the suffix of service name)
kafka_bootstrap_servers SW_KAFKA_BOOTSTRAP_SERVERS <class ‘str’> localhost:9092 A list of host/port pairs to use for establishing the initial connection to your Kafka cluster. It is in the form of host1:port1,host2:port2,… (used for Kafka reporter protocol)
kafka_namespace SW_KAFKA_NAMESPACE <class ‘str’> The kafka namespace specified by OAP side SW_NAMESPACE, prepends the following kafka topic names with a -.
kafka_topic_management SW_KAFKA_TOPIC_MANAGEMENT <class ‘str’> skywalking-managements Specifying Kafka topic name for service instance reporting and registering, this should be in sync with OAP
kafka_topic_segment SW_KAFKA_TOPIC_SEGMENT <class ‘str’> skywalking-segments Specifying Kafka topic name for Tracing data, this should be in sync with OAP
kafka_topic_log SW_KAFKA_TOPIC_LOG <class ‘str’> skywalking-logs Specifying Kafka topic name for Log data, this should be in sync with OAP
kafka_topic_meter SW_KAFKA_TOPIC_METER <class ‘str’> skywalking-meters Specifying Kafka topic name for Meter data, this should be in sync with OAP
kafka_reporter_custom_configurations SW_KAFKA_REPORTER_CUSTOM_CONFIGURATIONS <class ‘str’> The configs to init KafkaProducer, supports the basic arguments (whose type is either str, bool, or int) listed here This config only works from env variables, each one should be passed in SW_KAFKA_REPORTER_CONFIG_<KEY_NAME>
agent_force_tls SW_AGENT_FORCE_TLS <class ‘bool’> False Use TLS for communication with SkyWalking OAP (no cert required)
agent_authentication SW_AGENT_AUTHENTICATION <class ‘str’> The authentication token to verify that the agent is trusted by the backend OAP, as for how to configure the backend, refer to the yaml.
agent_logging_level SW_AGENT_LOGGING_LEVEL <class ‘str’> INFO The level of agent self-logs, could be one of CRITICAL, FATAL, ERROR, WARN(WARNING), INFO, DEBUG. Please turn on debug if an issue is encountered to find out what’s going on

Agent Core Danger Zone

Configuration Environment Variable Type Default Value Description
agent_collector_heartbeat_period SW_AGENT_COLLECTOR_HEARTBEAT_PERIOD <class ‘int’> 30 The agent will exchange heartbeat message with SkyWalking OAP backend every period seconds
agent_collector_properties_report_period_factor SW_AGENT_COLLECTOR_PROPERTIES_REPORT_PERIOD_FACTOR <class ‘int’> 10 The agent will report service instance properties every factor * heartbeat period seconds default: 10*30 = 300 seconds
agent_instance_properties_json SW_AGENT_INSTANCE_PROPERTIES_JSON <class ‘str’> A custom JSON string to be reported as service instance properties, e.g. {"key": "value"}
agent_experimental_fork_support SW_AGENT_EXPERIMENTAL_FORK_SUPPORT <class ‘bool’> False The agent will restart itself in any os.fork()-ed child process. Important Note: it’s not suitable for short-lived processes as each one will create a new instance in SkyWalking dashboard in format of service_instance-child(pid). This feature may not work when a precise combination of gRPC + Python 3.7 + subprocess (not fork) is used together. The agent will output a warning log when using on Python 3.7 for such a reason.
agent_queue_timeout SW_AGENT_QUEUE_TIMEOUT <class ‘int’> 1 DANGEROUS - This option controls the interval of each bulk report from telemetry data queues Do not modify unless you have evaluated its impact given your service load.
agent_asyncio_enhancement SW_AGENT_ASYNCIO_ENHANCEMENT <class ‘bool’> False Replace the threads to asyncio coroutines to report telemetry data to the OAP. This option is experimental and may not work as expected.

SW_PYTHON Auto Instrumentation CLI

Configuration Environment Variable Type Default Value Description
agent_sw_python_bootstrap_propagate SW_AGENT_SW_PYTHON_BOOTSTRAP_PROPAGATE <class ‘bool’> False Special: can only be passed via environment. This config controls the child process agent bootstrap behavior in sw-python CLI, if set to False, a valid child process will not boot up a SkyWalking Agent. Please refer to the CLI Guide for details.
agent_sw_python_cli_debug_enabled SW_AGENT_SW_PYTHON_CLI_DEBUG_ENABLED <class ‘bool’> False Special: can only be passed via environment. This config controls the CLI and agent logging debug mode, if set to True, the CLI and agent will print out debug logs. Please refer to the CLI Guide for details. Important: this config will set agent logging level to DEBUG as well, do not use it in production otherwise it will flood your logs. This normally shouldn’t be pass as a simple flag -d will be the same.

Trace Reporter Configurations

Configuration Environment Variable Type Default Value Description
agent_trace_reporter_max_buffer_size SW_AGENT_TRACE_REPORTER_MAX_BUFFER_SIZE <class ‘int’> 10000 The maximum queue backlog size for sending the segment data to backend, segments beyond this are silently dropped
agent_trace_ignore_path SW_AGENT_TRACE_IGNORE_PATH <class ‘str’> You can setup multiple URL path patterns, The endpoints match these patterns wouldn’t be traced. the current matching rules follow Ant Path match style , like /path/*, /path/**, /path/?.
agent_ignore_suffix SW_AGENT_IGNORE_SUFFIX <class ‘str’> .jpg,.jpeg,.js,.css,.png,.bmp,.gif,.ico,.mp3,.mp4,.html,.svg If the operation name of the first span is included in this set, this segment should be ignored.
correlation_element_max_number SW_CORRELATION_ELEMENT_MAX_NUMBER <class ‘int’> 3 Max element count of the correlation context.
correlation_value_max_length SW_CORRELATION_VALUE_MAX_LENGTH <class ‘int’> 128 Max value length of correlation context element.

Profiling Configurations

Configuration Environment Variable Type Default Value Description
agent_profile_active SW_AGENT_PROFILE_ACTIVE <class ‘bool’> True If True, Python agent will enable profiler when user create a new profiling task.
agent_collector_get_profile_task_interval SW_AGENT_COLLECTOR_GET_PROFILE_TASK_INTERVAL <class ‘int’> 20 The number of seconds between two profile task query.
agent_profile_max_parallel SW_AGENT_PROFILE_MAX_PARALLEL <class ‘int’> 5 The number of parallel monitor segment count.
agent_profile_duration SW_AGENT_PROFILE_DURATION <class ‘int’> 10 The maximum monitor segment time(minutes), if current segment monitor time out of limit, then stop it.
agent_profile_dump_max_stack_depth SW_AGENT_PROFILE_DUMP_MAX_STACK_DEPTH <class ‘int’> 500 The number of max dump thread stack depth
agent_profile_snapshot_transport_buffer_size SW_AGENT_PROFILE_SNAPSHOT_TRANSPORT_BUFFER_SIZE <class ‘int’> 50 The number of snapshot transport to backend buffer size

Log Reporter Configurations

Configuration Environment Variable Type Default Value Description
agent_log_reporter_active SW_AGENT_LOG_REPORTER_ACTIVE <class ‘bool’> True If True, Python agent will report collected logs to the OAP or Satellite. Otherwise, it disables the feature.
agent_log_reporter_safe_mode SW_AGENT_LOG_REPORTER_SAFE_MODE <class ‘bool’> False If True, Python agent will filter out HTTP basic auth information from log records. By default, it disables the feature due to potential performance impact brought by regular expression
agent_log_reporter_max_buffer_size SW_AGENT_LOG_REPORTER_MAX_BUFFER_SIZE <class ‘int’> 10000 The maximum queue backlog size for sending log data to backend, logs beyond this are silently dropped.
agent_log_reporter_level SW_AGENT_LOG_REPORTER_LEVEL <class ‘str’> WARNING This config specifies the logger levels of concern, any logs with a level below the config will be ignored.
agent_log_reporter_ignore_filter SW_AGENT_LOG_REPORTER_IGNORE_FILTER <class ‘bool’> False This config customizes whether to ignore the application-defined logger filters, if True, all logs are reported disregarding any filter rules.
agent_log_reporter_formatted SW_AGENT_LOG_REPORTER_FORMATTED <class ‘bool’> True If True, the log reporter will transmit the logs as formatted. Otherwise, puts logRecord.msg and logRecord.args into message content and tags(argument.n), respectively. Along with an exception tag if an exception was raised. Only applies to logging module.
agent_log_reporter_layout SW_AGENT_LOG_REPORTER_LAYOUT <class ‘str’> %(asctime)s [%(threadName)s] %(levelname)s %(name)s - %(message)s The log reporter formats the logRecord message based on the layout given. Only applies to logging module.
agent_cause_exception_depth SW_AGENT_CAUSE_EXCEPTION_DEPTH <class ‘int’> 10 This configuration is shared by log reporter and tracer. This config limits agent to report up to limit stacktrace, please refer to [Python traceback](../ https://docs.python.org/3/library/traceback.html#traceback.print_tb) for more explanations.

Meter Reporter Configurations

Configuration Environment Variable Type Default Value Description
agent_meter_reporter_active SW_AGENT_METER_REPORTER_ACTIVE <class ‘bool’> True If True, Python agent will report collected meters to the OAP or Satellite. Otherwise, it disables the feature.
agent_meter_reporter_max_buffer_size SW_AGENT_METER_REPORTER_MAX_BUFFER_SIZE <class ‘int’> 10000 The maximum queue backlog size for sending meter data to backend, meters beyond this are silently dropped.
agent_meter_reporter_period SW_AGENT_METER_REPORTER_PERIOD <class ‘int’> 20 The interval in seconds between each meter data report
agent_pvm_meter_reporter_active SW_AGENT_PVM_METER_REPORTER_ACTIVE <class ‘bool’> True If True, Python agent will report collected Python Virtual Machine (PVM) meters to the OAP or Satellite. Otherwise, it disables the feature.
Configuration Environment Variable Type Default Value Description
agent_disable_plugins SW_AGENT_DISABLE_PLUGINS <class ‘list’> [''] The name patterns in comma-separated pattern, plugins whose name matches one of the pattern won’t be installed
plugin_http_http_params_length_threshold SW_PLUGIN_HTTP_HTTP_PARAMS_LENGTH_THRESHOLD <class ‘int’> 1024 When COLLECT_HTTP_PARAMS is enabled, how many characters to keep and send to the OAP backend, use negative values to keep and send the complete parameters, NB. this config item is added for the sake of performance.
plugin_http_ignore_method SW_PLUGIN_HTTP_IGNORE_METHOD <class ‘str’> Comma-delimited list of http methods to ignore (GET, POST, HEAD, OPTIONS, etc…)
plugin_sql_parameters_max_length SW_PLUGIN_SQL_PARAMETERS_MAX_LENGTH <class ‘int’> 0 The maximum length of the collected parameter, parameters longer than the specified length will be truncated, length 0 turns off parameter tracing
plugin_pymongo_trace_parameters SW_PLUGIN_PYMONGO_TRACE_PARAMETERS <class ‘bool’> False Indicates whether to collect the filters of pymongo
plugin_pymongo_parameters_max_length SW_PLUGIN_PYMONGO_PARAMETERS_MAX_LENGTH <class ‘int’> 512 The maximum length of the collected filters, filters longer than the specified length will be truncated
plugin_elasticsearch_trace_dsl SW_PLUGIN_ELASTICSEARCH_TRACE_DSL <class ‘bool’> False If true, trace all the DSL(Domain Specific Language) in ElasticSearch access, default is false
plugin_flask_collect_http_params SW_PLUGIN_FLASK_COLLECT_HTTP_PARAMS <class ‘bool’> False This config item controls that whether the Flask plugin should collect the parameters of the request.
plugin_sanic_collect_http_params SW_PLUGIN_SANIC_COLLECT_HTTP_PARAMS <class ‘bool’> False This config item controls that whether the Sanic plugin should collect the parameters of the request.
plugin_django_collect_http_params SW_PLUGIN_DJANGO_COLLECT_HTTP_PARAMS <class ‘bool’> False This config item controls that whether the Django plugin should collect the parameters of the request.
plugin_fastapi_collect_http_params SW_PLUGIN_FASTAPI_COLLECT_HTTP_PARAMS <class ‘bool’> False This config item controls that whether the FastAPI plugin should collect the parameters of the request.
plugin_bottle_collect_http_params SW_PLUGIN_BOTTLE_COLLECT_HTTP_PARAMS <class ‘bool’> False This config item controls that whether the Bottle plugin should collect the parameters of the request.
plugin_celery_parameters_length SW_PLUGIN_CELERY_PARAMETERS_LENGTH <class ‘int’> 512 The maximum length of celery functions parameters, longer than this will be truncated, 0 turns off
plugin_grpc_ignored_methods SW_PLUGIN_GRPC_IGNORED_METHODS <class ‘str’> Comma-delimited list of user-defined grpc methods to ignore, like /package.Service/Method1,/package.Service/Method2

Sampling Configurations

Configuration Environment Variable Type Default Value Description
sample_n_per_3_secs SW_SAMPLE_N_PER_3_SECS <class ‘int’> 0 The number of samples to take in every 3 seconds, 0 turns off