github.com/yankunsam/loki/v2@v2.6.3-0.20220817130409-389df5235c27/docs/sources/clients/promtail/_index.md (about)

     1  ---
     2  title: Promtail
     3  weight: 10
     4  ---
     5  # Promtail
     6  
     7  Promtail is an agent which ships the contents of local logs to a private Grafana Loki
     8  instance or [Grafana Cloud](https://grafana.com/oss/loki). It is usually
     9  deployed to every machine that has applications needed to be monitored.
    10  
    11  It primarily:
    12  
    13  - Discovers targets
    14  - Attaches labels to log streams
    15  - Pushes them to the Loki instance.
    16  
    17  Currently, Promtail can tail logs from two sources: local log files and the
    18  systemd journal (on AMD64 machines only).
    19  
    20  ## Log file discovery
    21  
    22  Before Promtail can ship any data from log files to Loki, it needs to find out
    23  information about its environment. Specifically, this means discovering
    24  applications emitting log lines to files that need to be monitored.
    25  
    26  Promtail borrows the same
    27  [service discovery mechanism from Prometheus](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config),
    28  although it currently only supports `static` and `kubernetes` service
    29  discovery. This limitation is due to the fact that Promtail is deployed as a
    30  daemon to every local machine and, as such, does not discover label from other
    31  machines. `kubernetes` service discovery fetches required labels from the
    32  Kubernetes API server while `static` usually covers all other use cases.
    33  
    34  Just like Prometheus, `promtail` is configured using a `scrape_configs` stanza.
    35  `relabel_configs` allows for fine-grained control of what to ingest, what to
    36  drop, and the final metadata to attach to the log line. Refer to the docs for
    37  [configuring Promtail](configuration/) for more details.
    38  
    39  ## Loki Push API
    40  
    41  Promtail can also be configured to receive logs from another Promtail or any Loki client by exposing the [Loki Push API](../../api#post-lokiapiv1push) with the [loki_push_api](configuration#loki_push_api_config) scrape config.
    42  
    43  There are a few instances where this might be helpful:
    44  
    45  - complex network infrastructures where many machines having egress is not desirable.
    46  - using the Docker Logging Driver and wanting to provide a complex pipeline or to extract metrics from logs.
    47  - serverless setups where many ephemeral log sources want to send to Loki, sending to a Promtail instance with `use_incoming_timestamp` == false can avoid out-of-order errors and avoid having to use high cardinality labels.
    48  
    49  ## Receiving logs From Syslog
    50  
    51  When the [Syslog Target](configuration#syslog_config) is being used, logs
    52  can be written with the syslog protocol to the configured port.
    53  
    54  ## AWS
    55  
    56  If you need to run Promtail on Amazon Web Services EC2 instances, you can use our [detailed tutorial](../aws/ec2/).
    57  
    58  ## Labeling and parsing
    59  
    60  During service discovery, metadata is determined (pod name, filename, etc.) that
    61  may be attached to the log line as a label for easier identification when
    62  querying logs in Loki. Through `relabel_configs`, discovered labels can be
    63  mutated into the desired form.
    64  
    65  To allow more sophisticated filtering afterwards, Promtail allows to set labels
    66  not only from service discovery, but also based on the contents of each log
    67  line. The `pipeline_stages` can be used to add or update labels, correct the
    68  timestamp, or re-write log lines entirely. Refer to the documentation for
    69  [pipelines](pipelines/) for more details.
    70  
    71  ## Shipping
    72  
    73  Once Promtail has a set of targets (i.e., things to read from, like files) and
    74  all labels are set correctly, it will start tailing (continuously reading) the
    75  logs from targets. Once enough data is read into memory or after a configurable
    76  timeout, it is flushed as a single batch to Loki.
    77  
    78  As Promtail reads data from sources (files and systemd journal, if configured),
    79  it will track the last offset it read in a positions file. By default, the
    80  positions file is stored at `/var/log/positions.yaml`. The positions file helps
    81  Promtail continue reading from where it left off in the case of the Promtail
    82  instance restarting.
    83  
    84  ## API
    85  
    86  Promtail features an embedded web server exposing a web console at `/` and the following API endpoints:
    87  
    88  ### `GET /ready`
    89  
    90  This endpoint returns 200 when Promtail is up and running, and there's at least one working target.
    91  
    92  ### `GET /metrics`
    93  
    94  This endpoint returns Promtail metrics for Prometheus. Refer to
    95  [Observing Grafana Loki](../../operations/observability/) for the list
    96  of exported metrics.
    97  
    98  ### Promtail web server config
    99  
   100  The web server exposed by Promtail can be configured in the Promtail `.yaml` config file:
   101  
   102  ```yaml
   103  server:
   104    http_listen_address: 127.0.0.1
   105    http_listen_port: 9080
   106  ```