github.com/pinpoint-apm/pinpoint-go-agent@v1.4.1-0.20240110120318-a50c2eb18c8c/doc/config.md (about) 1 # Pinpoint Go Agent Configuration 2 3 ## Overview 4 Pinpoint Go Agent creates a Config populated with default settings, command line flags, environment variables, config file 5 and config functions are prefixed with 'With', such as WithAppName. 6 Config uses the following precedence order. 7 Each item takes precedence over the item below it: 8 9 1. command line flag 10 2. environment variable 11 3. config file 12 4. config function 13 5. default 14 15 For example, if a configuration item is specified in the environment variable and in the configuration file respectively, 16 the value set in the environment variable is finally used. 17 18 ### Dynamic Configuration 19 Pinpoint Go Agent supports the ability to have your application live read a config file while running. 20 Configuration options marked with the **dynamic** can be changed at runtime when you change the config file. 21 22 ## Configuration Option 23 The titles below are used as configuration keys in config file. 24 In the description of each config option below, the list is shown in the order command flag, environment variable, 25 config function, value type and additional information. 26 27 ### ConfigFile 28 The config options below can be saved to the config file is set by ConfigFile option. 29 It is supported JSON, YAML and Properties config files 30 and configuration keys used in config files are case-insensitive. 31 32 * --pinpoint-configfile 33 * PINPOINT_GO_CONFIGFILE 34 * WithConfigFile() 35 * string 36 * case-sensitive 37 38 For `.` delimited path keys, they are accessed in nested field. 39 The format of the YAML config file is as follows: 40 ``` yaml 41 applicationName: "MyAppName" 42 collector: 43 host: "collector.myhost.com" 44 sampling: 45 type: "percent" 46 percentRate: 10 47 logLevel: "error" 48 ``` 49 50 * [YAML File Example](/example/pinpoint-config.yaml) 51 * [JSON File Example](/example/pinpoint-config.json) 52 * [Properties File Example](/example/pinpoint-config.prop) 53 54 ### ActiveProfile 55 The configuration profile feature is supported. 56 You can set the profile in the config file and specify the profile to activate with the ActiveProfile option. 57 58 * --pinpoint-activeprofile 59 * PINPOINT_GO_ACTIVEPROFILE 60 * WithActiveProfile() 61 * string 62 * case-insensitive 63 64 The example below shows that config file and profile are set by command flag. 65 ``` 66 --pinpoint-configfile=pinpoint-config.json --pinpoint-activeprofile=dev 67 ``` 68 ```json 69 { 70 "applicationName": "JsonAppName", 71 "agentId": "JsonAgentID", 72 "loglevel": "debug", 73 "profile": { 74 "dev": { 75 "collector": { 76 "host": "dev.collector.host" 77 }, 78 "sampling": { 79 "type": "COUNTER", 80 "CounterRate": 1 81 } 82 }, 83 "real": { 84 "collector": { 85 "host": "real.collector.host" 86 }, 87 "sampling": { 88 "type": "percent", 89 "percentRate": 5.5 90 } 91 } 92 } 93 } 94 ``` 95 96 ### ApplicationName 97 ApplicationName option sets the application name. 98 If this option is not provided, the agent can't be started. 99 The maximum length of ApplicationName is 24. 100 101 * --pinpoint-applicationname 102 * PINPOINT_GO_APPLICATIONNAME 103 * WithAppName() 104 * string 105 * case-sensitive 106 107 ### ApplicationType 108 ApplicationType option sets the application type. 109 110 * --pinpoint-applicationtype 111 * PINPOINT_GO_APPLICATIONTYPE 112 * WithAppType() 113 * int 114 * default: 1800 (ServiceTypeGoApp) 115 116 ### AgentId 117 AgentId option set id to distinguish agent. 118 We recommend that you enable hostname to be included. 119 The maximum length of AgentId is 24. 120 If agent id is not set or the maximum length is exceeded, automatically generated id is given. 121 122 * --pinpoint-agentid 123 * PINPOINT_GO_AGENTID 124 * WithAgentId() 125 * string 126 * case-sensitive 127 128 ### AgentName 129 AgentName option sets the agent name. 130 The maximum length of AgentName is 255. 131 132 * --pinpoint-agentname 133 * PINPOINT_GO_AGENTNAME 134 * WithAgentName() 135 * string 136 * case-sensitive 137 138 ### Collector.Host 139 Collector.Host option sets the host address of Pinpoint collector. 140 141 * --pinpoint-collector-host 142 * PINPOINT_GO_COLLECTOR_HOST 143 * WithCollectorHost() 144 * string 145 * default: "localhost" 146 * case-sensitive 147 148 ### Collector.AgentPort 149 Collector.AgentPort option sets the agent port of Pinpoint collector. 150 151 * --pinpoint-collector-agentport 152 * PINPOINT_GO_COLLECTOR_AGENTPORT 153 * WithCollectorAgentPort() 154 * int 155 * default: 9991 156 157 ### Collector.SpanPort 158 Collector.SpanPort option sets the span port of Pinpoint collector. 159 160 * --pinpoint-collector-spanport 161 * PINPOINT_GO_COLLECTOR_SPANPORT 162 * WithCollectorSpanPort() 163 * int 164 * default: 9993 165 166 ### Collector.StatPort 167 Collector.StatPort option sets the stat port of Pinpoint collector. 168 169 * --pinpoint-collector-statport 170 * PINPOINT_GO_COLLECTOR_STATPORT 171 * WithCollectorStatPort() 172 * int 173 * default: 9992 174 175 ### Sampling.Type 176 Sampling.Type option sets the type of agent sampler. 177 Either "COUNTER" or "PERCENT" must be specified. 178 179 * --pinpoint-sampling-type 180 * PINPOINT_GO_SAMPLING_TYPE 181 * WithSamplingType() 182 * string 183 * default: "COUNTER" 184 * case-insensitive 185 * dynamic 186 187 ### Sampling.CounterRate 188 Sampling.CounterRate option sets the counter sampling rate. 189 Sample 1/rate. In other words, if the rate is 1, then it will be 100% and if it is 100, it will be 1% sampling. 190 191 * --pinpoint-sampling-counterrate 192 * PINPOINT_GO_SAMPLING_COUNTERRATE 193 * WithSamplingCounterRate() 194 * int 195 * default: 1 196 * valid range: 0 ~ 100 197 * dynamic 198 199 ### Sampling.PercentRate 200 Sampling.PercentRate option sets the sampling rate for a 'percent sampler'. 201 202 * --pinpoint-sampling-percentrate 203 * PINPOINT_GO_SAMPLING_PERCENTRATE 204 * WithSamplingPercentRate() 205 * float 206 * default: 100 207 * valid range: 0.01 ~ 100 208 * dynamic 209 210 ### Sampling.NewThroughput 211 Sampling.NewThroughput option sets the new TPS for a 'throughput sampler'. 212 213 * --pinpoint-sampling-newthroughput 214 * PINPOINT_GO_SAMPLING_NEWTHROUGHPUT 215 * WithSamplingNewThroughput() 216 * type: int 217 * default: 0 218 * dynamic 219 220 ### Sampling.ContinueThroughput 221 Sampling.ContinueThroughput option sets the cont TPS for a 'throughput sampler'. 222 223 * --pinpoint-sampling-continuethroughput 224 * PINPOINT_GO_SAMPLING_CONTINUETHROUGHPUT 225 * WithSamplingContinueThroughput() 226 * type: int 227 * default: 0 228 * dynamic 229 230 ### Span.QueueSize 231 Span.QueueSize option sets the size of agent's span queue for gRPC. 232 233 * --pinpoint-span-queuesize 234 * PINPOINT_GO_SPAN_QUEUESIZE 235 * WithSpanQueueSize() 236 * type: int 237 * default: 1024 238 239 ### Span.MaxCallStackDepth 240 Span.MaxCallStackDepth option sets the max callstack depth of a span, if -1 is unlimited and min is 2. 241 242 * --pinpoint-span-maxcallstackdepth 243 * PINPOINT_GO_SPAN_MAXCALLSTACKDEPTH 244 * WithSpanMaxCallStackDepth() 245 * type: int 246 * default: 64 247 * dynamic 248 249 ### Span.MaxCallStackSequence 250 Span.MaxCallStackDepth option sets the max callstack sequence of a span, if -1 is unlimited and min is 4. 251 252 * --pinpoint-span-maxcallstacksequence 253 * PINPOINT_GO_SPAN_MAXCALLSTACKSEQUENCE 254 * WithSpanMaxCallStackSequence() 255 * type: int 256 * default: 5000 257 * dynamic 258 259 ### Stat.CollectInterval 260 Stat.CollectInterval option sets the statistics collection cycle for the agent. 261 262 * --pinpoint-stat-collectinterval 263 * PINPOINT_GO_STAT_COLLECTINTERVAL 264 * WithStatCollectInterval() 265 * type: int 266 * default: 5000 267 * unit: milliseconds 268 269 ### Stat.BatchCount 270 Stat.BatchCount option sets batch delivery units for collected statistics. 271 272 * --pinpoint-stat-batchcount 273 * PINPOINT_GO_STAT_BATCHCOUNT 274 * WithStatBatchCount() 275 * type: int 276 * default: 6 277 278 ### SQL.TraceBindValue 279 SQL.TraceBindValue option enables bind value tracing for SQL Driver. 280 281 * --pinpoint-sql-tracebindvalue 282 * PINPOINT_GO_SQL_TRACEBINDVALUE 283 * WithSQLTraceBindValue() 284 * type: bool 285 * default: true 286 * dynamic 287 288 ### SQL.MaxBindValueSize 289 SQL.MaxBindValueSize option sets the max length of traced bind value for SQL Driver. 290 291 * --pinpoint-sql-maxbindvaluesize 292 * PINPOINT_GO_SQL_MAXBINDVALUESIZE 293 * WithSQLMaxBindValueSize() 294 * type: int 295 * default: 1024 296 * unit: bytes 297 * dynamic 298 299 ### SQL.TraceCommit 300 SQL.TraceCommit option enables commit tracing for SQL Driver. 301 302 * --pinpoint-sql-tracecommit 303 * PINPOINT_GO_SQL_TRACECOMMIT 304 * WithSQLTraceCommit() 305 * type: bool 306 * default: true 307 * dynamic 308 309 ### SQL.TraceRollback 310 SQL.TraceRollback option enables rollback tracing for SQL Driver. 311 312 * --pinpoint-sql-tracerollback 313 * PINPOINT_GO_SQL_TRACEROLLBACK 314 * WithSQLTraceRollback() 315 * type: bool 316 * default: true 317 * dynamic 318 319 ### SQL.TraceQueryStat 320 SQL.TraceQueryStat option enables trace SQL query statistics. 321 322 * --pinpoint-sql-tracequerystat 323 * PINPOINT_GO_SQL_TRACEQUERYSTAT 324 * WithSQLTraceQueryStat() 325 * type: bool 326 * default: false 327 * dynamic 328 329 330 ### Log.Level 331 Log.Level option sets the level of log generated by the agent. 332 Either trace, debug, info, warn, or error must be set. 333 334 * --pinpoint-log-level 335 * PINPOINT_GO_LOG_LEVEL 336 * WithLogLevel() 337 * type: string 338 * default: "info" 339 * case-insensitive 340 * dynamic 341 342 ### Log.Output 343 Log.Output option sets the output file of log generated by the agent. 344 You can set stderr, stdout or file path. 345 346 * --pinpoint-log-output 347 * PINPOINT_GO_LOG_OUTPUT 348 * WithLogOutput() 349 * type: string 350 * default: "stderr" 351 * case-insensitive 352 * dynamic 353 354 ### Log.MaxSize 355 Log.MaxSize option sets the max size of log file. The unit of value is MB. 356 357 * --pinpoint-log-maxsize 358 * PINPOINT_GO_LOG_MAXSIZE 359 * WithLogMaxSize() 360 * type: int 361 * default: 10 362 * dynamic 363 364 ### Error.TraceCallStack 365 Error.TraceCallStack option enables trace callstack dump when a error occurs. 366 367 * --pinpoint-error-tracecallstack 368 * PINPOINT_GO_ERROR_TRACECALLSTACK 369 * WithErrorTraceCallStack() 370 * type: bool 371 * default: false 372 * dynamic 373 374 ### Error.CallStackDepth 375 Error.CallStackDepth option sets the max depth of callstack to be dumped. 376 377 * --pinpoint-error-callstackdepth 378 * PINPOINT_GO_ERROR_CALLSTACKDEPTH 379 * WithErrorCallStackDepth() 380 * type: int 381 * default: 32 382 * dynamic 383 384 ### IsContainerEnv 385 IsContainerEnv option sets whether the application is running in a container environment or not. 386 If this is not set, the agent automatically checks it. 387 388 * --pinpoint-iscontainerenv 389 * PINPOINT_GO_ISCONTAINERENV 390 * WithIsContainerEnv() 391 * type: bool 392 * default: false 393 394 ### Enable 395 Enable option enables the agent is operational state. 396 If this is set as false, the agent doesn't start working. 397 398 * --pinpoint-enable 399 * PINPOINT_GO_ENABLE 400 * WithEnable() 401 * type: bool 402 * default: true 403 404 ### Http.Server.StatusCodeErrors 405 Http.Server.StatusCodeErrors option sets HTTP status code with request failure. 406 Refer https://pinpoint-apm.gitbook.io/pinpoint/documents/http-status-code-failure. 407 408 * --pinpoint-http-server-statuscodeerrors 409 * PINPOINT_GO_HTTP_SERVER_STATUSCODEERRORS 410 * WithHttpServerStatusCodeError() 411 * type: string slice 412 * default: {"5xx"} 413 * case-insensitive 414 * dynamic 415 416 The string slice value is set as follows. 417 ``` 418 --pinpoint-http-server-statuscodeerrors=5xx,301,400 419 ``` 420 ``` 421 export PINPOINT_GO_HTTP_SERVER_STATUSCODEERRORS=5xx,301,400 422 ``` 423 ``` yaml 424 http: 425 server: 426 statusCodeErrors: 427 - 5xx 428 - 301 429 - 400 430 ``` 431 432 ### Http.Server.ExcludeUrl 433 Http.Server.ExcludeUrl option sets URLs to exclude from tracking. 434 It supports ant style pattern. (e.g. /aa/*.html, /??/exclude.html) 435 Refer https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/util/AntPathMatcher.html. 436 437 * --pinpoint-http-server-excludeurl 438 * PINPOINT_GO_HTTP_SERVER_EXCLUDEURL 439 * WithHttpServerExcludeUrl() 440 * type: string slice 441 * case-sensitive 442 * dynamic 443 444 ### Http.Server.ExcludeMethod 445 Http.Server.ExcludeMethod option sets HTTP Request methods to exclude from tracking. 446 447 * --pinpoint-http-server-excludemethod 448 * PINPOINT_GO_HTTP_SERVER_EXCLUDEMETHOD 449 * WithHttpServerExcludeMethod() 450 * type: string slice 451 * case-insensitive 452 * dynamic 453 454 ### Http.Server.RecordRequestHeader 455 Http.Server.RecordRequestHeader option sets HTTP request headers to be logged on the server side. 456 If sets to "HEADERS-ALL", it records all request headers. 457 458 * --pinpoint-http-server-recordrequestheader 459 * PINPOINT_GO_HTTP_SERVER_RECORDREQUESTHEADER 460 * WithHttpServerRecordRequestHeader() 461 * type: string slice 462 * case-insensitive 463 * dynamic 464 465 ### Http.Server.RecordResponseHeader 466 Http.Server.RecordResponseHeader option sets HTTP response headers to be logged on the server side. 467 If sets to "HEADERS-ALL", it records all request headers. 468 469 * --pinpoint-http-server-recordresponseheader 470 * PINPOINT_GO_HTTP_SERVER_RECORDRESPONSEHEADER 471 * WithHttpServerRecordRespondHeader() 472 * type: string slice 473 * case-insensitive 474 * dynamic 475 476 ### Http.Server.RecordRequestCookie 477 Http.Server.RecordRequestCookie option sets HTTP request cookies to be logged on the server side. 478 If sets to "HEADERS-ALL", it records all request headers. 479 480 * --pinpoint-http-server-recordrequestcookie 481 * PINPOINT_GO_HTTP_SERVER_RECORDREQUESTCOOKIE 482 * WithHttpServerRecordRequestCookie() 483 * type: string slice 484 * case-insensitive 485 * dynamic 486 487 ### Http.Client.RecordRequestHeader 488 Http.Client.RecordRequestHeader option sets HTTP request headers to be logged on the client side. 489 If sets to "HEADERS-ALL", it records all request headers. 490 491 * --pinpoint-http-client-recordrequestheader 492 * PINPOINT_GO_HTTP_CLIENT_RECORDREQUESTHEADER 493 * WithHttpClientRecordRequestHeader() 494 * type: string slice 495 * case-insensitive 496 * dynamic 497 498 ### Http.Client.RecordResponseHeader 499 Http.Client.RecordResponseHeader option sets HTTP response headers to be logged on the client side. 500 If sets to "HEADERS-ALL", it records all request headers. 501 502 * --pinpoint-http-client-recordresponseheader 503 * PINPOINT_GO_HTTP_CLIENT_RECORDRESPONSEHEADER 504 * WithHttpClientRecordRespondHeader() 505 * type: string slice 506 * case-insensitive 507 * dynamic 508 509 ### Http.Client.RecordRequestCookie 510 Http.Client.RecordRequestCookie option sets HTTP request cookies to be logged on the client side. 511 If sets to "HEADERS-ALL", it records all request headers. 512 513 * --pinpoint-http-client-recordrequestcookie 514 * PINPOINT_GO_HTTP_CLIENT_RECORDREQUESTCOOKIE 515 * WithHttpClientRecordRequestCookie() 516 * type: string slice 517 * case-insensitive 518 * dynamic 519 520 ### Http.UrlStat.Enable 521 Http.UrlStat.Enable option enables the agent's HTTP URL statistics feature. 522 If this is set as false, the agent doesn't collect HTTP URL statistics. 523 Pinpoint Go Agent collects response times, successes and failures for all http requests regardless of sampling. 524 The HTTP URL statistics feature is supported from Pinpoint version 2.5.0. 525 526 * --pinpoint-http-urlstat-enable 527 * PINPOINT_GO_HTTP_URLSTAT_ENABLE 528 * WithHttpUrlStatEnable() 529 * type: bool 530 * default: false 531 * dynamic 532 533 ### Http.UrlStat.LimitSize 534 Http.UrlStat.LimitSize option sets the limit size of the URLs to be collected. 535 536 * --pinpoint-http-urlstat-limitsize 537 * PINPOINT_GO_HTTP_URLSTAT_LIMITSIZE 538 * WithHttpUrlStatLimitSize() 539 * type: int 540 * default: 1024 541 * dynamic 542 543 ### Http.UrlStat.WithMethod 544 Http.UrlStat.WithMethod option adds http method as prefix to url string key. 545 546 * --pinpoint-http-urlstat-withmethod 547 * PINPOINT_GO_HTTP_URLSTAT_WITHMETHOD 548 * WithHttpUrlStatWithMethod() 549 * type: bool 550 * default: false 551 * dynamic