plugin_name: go.d.plugin
modules:
  - meta:
      id: collector-go.d.plugin-squidlog
      plugin_name: go.d.plugin
      module_name: squidlog
      monitored_instance:
        name: Squid log files
        link: https://www.lighttpd.net/
        icon_filename: squid.png
        categories:
          - data-collection.web-servers-and-web-proxies
      keywords:
        - squid
        - logs
      related_resources:
        integrations:
          list: []
      info_provided_to_referring_integrations:
        description: ""
      most_popular: true
    overview:
      data_collection:
        metrics_description: |
          his collector monitors Squid servers by parsing their access log files.
        method_description: |
          It automatically detects log files of Squid severs running on localhost.
      supported_platforms:
        include: []
        exclude: []
      multi_instance: true
      additional_permissions:
        description: ""
      default_behavior:
        auto_detection:
          description: ""
        limits:
          description: ""
        performance_impact:
          description: ""
    setup:
      prerequisites:
        list: []
      configuration:
        file:
          name: go.d/squidlog.conf
        options:
          description: |
            Squid [log format codes](https://www.squid-cache.org/Doc/config/logformat/).

            Squidlog is aware how to parse and interpret the following codes:

            | field          | squid format code | description                                                   |
            |----------------|-------------------|---------------------------------------------------------------|
            | resp_time      | %tr               | Response time (milliseconds).                                 |
            | client_address | %>a               | Client source IP address.                                     |
            | client_address | %>A               | Client FQDN.                                                  |
            | cache_code     | %Ss               | Squid request status (TCP_MISS etc).                          |
            | http_code      | %>Hs              | The HTTP response status code from Content Gateway to client. |
            | resp_size      | %<st              | Total size of reply sent to client (after adaptation).        |
            | req_method     | %rm               | Request method (GET/POST etc).                                |
            | hier_code      | %Sh               | Squid hierarchy status (DEFAULT_PARENT etc).                  |
            | server_address | %<a               | Server IP address of the last server or peer connection.      |
            | server_address | %<A               | Server FQDN or peer name.                                     |
            | mime_type      | %mt               | MIME content type.                                            |

            In addition, to make `Squid` [native log format](https://wiki.squid-cache.org/Features/LogFormat#Squid_native_access.log_format_in_detail) csv parsable, squidlog understands these groups of codes:

            | field       | squid format code | description                        |
            |-------------|-------------------|------------------------------------|
            | result_code | %Ss/%>Hs          | Cache code and http code.          |
            | hierarchy   | %Sh/%<a           | Hierarchy code and server address. |
          folding:
            title: Config options
            enabled: true
          list:
            - name: update_every
              description: Data collection frequency.
              default_value: 1
              required: false
            - name: autodetection_retry
              description: Recheck interval in seconds. Zero means no recheck will be scheduled.
              default_value: 0
              required: false
            - name: path
              description: Path to the Squid access log file.
              default_value: /var/log/squid/access.log
              required: true
            - name: exclude_path
              description: Path to exclude.
              default_value: "*.gz"
              required: false
            - name: parser
              description: Log parser configuration.
              default_value: ""
              required: false
            - name: parser.log_type
              description: Log parser type.
              default_value: auto
              required: false
              detailed_description: |
                Weblog supports 3 different log parsers:

                | Parser type | Description                               |
                |-------------|-------------------------------------------|
                | csv         | A comma-separated values                  |
                | ltsv        | [LTSV](http://ltsv.org/)                  |
                | regexp      | Regular expression with named groups      |
                
                Syntax:

                ```yaml
                parser:
                  log_type: csv
                ```
            - name: parser.csv_config
              description: CSV log parser config.
              default_value: ""
              required: false
            - name: parser.csv_config.delimiter
              description: CSV field delimiter.
              default_value: space
              required: false
            - name: parser.csv_config.format
              description: CSV log format.
              default_value: "- $resp_time $client_address $result_code $resp_size $req_method - - $hierarchy $mime_type"
              required: true
              detailed_description: ""
            - name: parser.ltsv_config
              description: LTSV log parser config.
              default_value: ""
              required: false
            - name: parser.ltsv_config.field_delimiter
              description: LTSV field delimiter.
              default_value: "\\t"
              required: false
            - name: parser.ltsv_config.value_delimiter
              description: LTSV value delimiter.
              default_value: ":"
              required: false
            - name: parser.ltsv_config.mapping
              description: LTSV fields mapping to **known fields**.
              default_value: ""
              required: true
              detailed_description: |
                The mapping is a dictionary where the key is a field, as in logs, and the value is the corresponding **known field**.

                > **Note**: don't use `$` and `%` prefixes for mapped field names.

                ```yaml
                parser:
                  log_type: ltsv
                  ltsv_config:
                    mapping:
                      label1: field1
                      label2: field2
                ```
            - name: parser.regexp_config
              description: RegExp log parser config.
              default_value: ""
              required: false
            - name: parser.regexp_config.pattern
              description: RegExp pattern with named groups.
              default_value: ""
              required: true
              detailed_description: |
                Use pattern with subexpressions names. These names should be **known fields**.
                
                > **Note**: don't use `$` and `%` prefixes for mapped field names.

                Syntax:

                ```yaml
                parser:
                  log_type: regexp
                  regexp_config:
                    pattern: PATTERN
                ```
        examples:
          folding:
            title: Config
            enabled: true
          list: []
    troubleshooting:
      problems:
        list: []
    alerts: []
    metrics:
      folding:
        title: Metrics
        enabled: false
      description: ""
      availability: []
      scopes:
        - name: global
          description: These metrics refer to the entire monitored application.
          labels: []
          metrics:
            - name: squidlog.requests
              description: Total Requests
              unit: requests/s
              chart_type: line
              dimensions:
                - name: requests
            - name: squidlog.excluded_requests
              description: Excluded Requests
              unit: requests/s
              chart_type: line
              dimensions:
                - name: unmatched
            - name: squidlog.type_requests
              description: Requests By Type
              unit: requests/s
              chart_type: stacked
              dimensions:
                - name: success
                - name: bad
                - name: redirect
                - name: error
            - name: squidlog.http_status_code_class_responses
              description: Responses By HTTP Status Code Class
              unit: responses/s
              chart_type: stacked
              dimensions:
                - name: 1xx
                - name: 2xx
                - name: 3xx
                - name: 4xx
                - name: 5xx
            - name: squidlog.http_status_code_responses
              description: Responses By HTTP Status Code
              unit: responses/s
              chart_type: stacked
              dimensions:
                - name: a dimension per HTTP response code
            - name: squidlog.bandwidth
              description: Bandwidth
              unit: kilobits/s
              chart_type: line
              dimensions:
                - name: sent
            - name: squidlog.response_time
              description: Response Time
              unit: milliseconds
              chart_type: line
              dimensions:
                - name: min
                - name: max
                - name: avg
            - name: squidlog.uniq_clients
              description: Unique Clients
              unit: clients
              chart_type: line
              dimensions:
                - name: clients
            - name: squidlog.cache_result_code_requests
              description: Requests By Cache Result Code
              unit: requests/s
              chart_type: stacked
              dimensions:
                - name: a dimension per cache result code
            - name: squidlog.cache_result_code_transport_tag_requests
              description: Requests By Cache Result Delivery Transport Tag
              unit: requests/s
              chart_type: stacked
              dimensions:
                - name: a dimension per cache result delivery transport tag
            - name: squidlog.cache_result_code_handling_tag_requests
              description: Requests By Cache Result Handling Tag
              unit: requests/s
              chart_type: stacked
              dimensions:
                - name: a dimension per cache result handling tag
            - name: squidlog.cache_code_object_tag_requests
              description: Requests By Cache Result Produced Object Tag
              unit: requests/s
              chart_type: stacked
              dimensions:
                - name: a dimension per cache result produced object tag
            - name: squidlog.cache_code_load_source_tag_requests
              description: Requests By Cache Result Load Source Tag
              unit: requests/s
              chart_type: stacked
              dimensions:
                - name: a dimension per cache result load source tag
            - name: squidlog.cache_code_error_tag_requests
              description: Requests By Cache Result Errors Tag
              unit: requests/s
              chart_type: stacked
              dimensions:
                - name: a dimension per cache result error tag
            - name: squidlog.http_method_requests
              description: Requests By HTTP Method
              unit: requests/s
              chart_type: stacked
              dimensions:
                - name: a dimension per HTTP method
            - name: squidlog.mime_type_requests
              description: Requests By MIME Type
              unit: requests/s
              chart_type: stacked
              dimensions:
                - name: a dimension per MIME type
            - name: squidlog.hier_code_requests
              description: Requests By Hierarchy Code
              unit: requests/s
              chart_type: stacked
              dimensions:
                - name: a dimension per hierarchy code
            - name: squidlog.server_address_forwarded_requests
              description: Forwarded Requests By Server Address
              unit: requests/s
              chart_type: stacked
              dimensions:
                - name: a dimension per server address
