This is an automated email from the ASF dual-hosted git repository.
wusheng pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/skywalking.git
The following commit(s) were added to refs/heads/master by this push:
new f94bf97 Refine lal.md (#6626)
f94bf97 is described below
commit f94bf971fdf8beb4905ac140fcde93dcf2e1af62
Author: Wing <[email protected]>
AuthorDate: Fri Mar 26 12:04:55 2021 +0800
Refine lal.md (#6626)
---
docs/en/concepts-and-designs/lal.md | 58 ++++++++++++++++++-------------------
1 file changed, 28 insertions(+), 30 deletions(-)
diff --git a/docs/en/concepts-and-designs/lal.md
b/docs/en/concepts-and-designs/lal.md
index c3f1af4..ac6e1b7 100644
--- a/docs/en/concepts-and-designs/lal.md
+++ b/docs/en/concepts-and-designs/lal.md
@@ -1,32 +1,31 @@
# Log Analysis Language
Log Analysis Language (LAL) in SkyWalking is essentially a Domain-Specific
Language (DSL) to analyze logs. You can use
-LAL to parse, extract, and save the logs, as well as collaborate the logs with
traces (by extracting the trace id,
-segment id and span id) and metrics (by generating metrics from the logs and
send them to the meter system).
+LAL to parse, extract, and save the logs, as well as collaborate the logs with
traces (by extracting the trace ID,
+segment ID and span ID) and metrics (by generating metrics from the logs and
sending them to the meter system).
-The LAL config files are in YAML format, and are located under directory
`lal`, you can
+The LAL config files are in YAML format, and are located under directory
`lal`. You can
set `log-analyzer/default/lalFiles` in the `application.yml` file or set
environment variable `SW_LOG_LAL_FILES` to
activate specific LAL config files.
## Filter
A filter is a group of [parser](#parser), [extractor](#extractor) and
[sink](#sink). Users can use one or more filters
-to organize their processing logics. Every piece of log will be sent to all
filters in an LAL rule. The piece of log
-sent into the filter is available as property `log` in the LAL, therefore you
can access the log service name
-via `log.service`, for all available fields of `log`, please refer to [the
protocol
definition](https://github.com/apache/skywalking-data-collect-protocol/blob/master/logging/Logging.proto#L41).
+to organize their processing logic. Every piece of log will be sent to all
filters in an LAL rule. A piece of log
+sent to the filter is available as property `log` in the LAL, therefore you
can access the log service name
+via `log.service`. For all available fields of `log`, please refer to [the
protocol
definition](https://github.com/apache/skywalking-data-collect-protocol/blob/master/logging/Logging.proto#L41).
All components are executed sequentially in the orders they are declared.
### Global Functions
-There are functions globally available that you can use them in all components
(i.e. parsers, extractors, and sinks)
-when needed.
+Globally available functions may be used them in all components (i.e. parsers,
extractors, and sinks) where necessary.
- `abort`
By default, all components declared are executed no matter what flags
(`dropped`, `saved`, etc.) have been set. There
are cases where you may want the filter chain to stop earlier when specified
conditions are met. `abort` function aborts
-the remaining filter chain from where it's declared, all the remaining
components won't be executed at all.
+the remaining filter chain from where it's declared, and all the remaining
components won't be executed at all.
`abort` function serves as a fast-fail mechanism in LAL.
```groovy
@@ -47,8 +46,8 @@ Parsers are responsible for parsing the raw logs into
structured data in SkyWalk
types of parsers at the moment, namely `json`, `yaml`, and `text`.
When a piece of log is parsed, there is a corresponding property available,
called `parsed`, injected by LAL.
-Property `parsed` is typically a map, containing all the fields parsed from
the raw logs, for example, if the parser
-is `json` / `yaml`, `parsed` is a map containing all the key-values in the
`json` / `yaml`, if the parser is `text`
+Property `parsed` is typically a map, containing all the fields parsed from
the raw logs. For example, if the parser
+is `json` / `yaml`, `parsed` is a map containing all the key-values in the
`json` / `yaml`; if the parser is `text`
, `parsed` is a map containing all the captured groups and their values (for
`regexp` and `grok`).
All parsers share the following options:
@@ -108,7 +107,7 @@ filter {
- `grok` (TODO)
-Because grok Java library has performance issue, we need some investigations
and benchmark on it. Contributions are
+We're aware of certains performance issues in the grok Java library, and so
we're currently conducting investigations and benchmarking. Contributions are
welcome.
### Extractor
@@ -155,8 +154,7 @@ The unit of `timestamp` is millisecond.
- `tag`
-`tag` extracts the tags from the `parsed` result, and set them into the
`LogData`. The form of this extractor is
-something like `tag key1: value, key2: value2`, you can use the properties of
`parsed` as both keys and values.
+`tag` extracts the tags from the `parsed` result, and set them into the
`LogData`. The form of this extractor should look something like this: `tag
key1: value, key2: value2`. You may use the properties of `parsed` as both keys
and values.
```groovy
filter {
@@ -171,9 +169,9 @@ filter {
- `metrics`
-`metrics` extracts / generates metrics from the logs, and sends the generated
metrics to the meter system, you can
+`metrics` extracts / generates metrics from the logs, and sends the generated
metrics to the meter system. You may
configure [MAL](mal.md) for further analysis of these metrics. The dedicated
MAL config files are under
-directory `log-mal-rules`, you can set `log-analyzer/default/malFiles` to
enable configured files.
+directory `log-mal-rules`, and you can set `log-analyzer/default/malFiles` to
enable configured files.
```yaml
# application.yml
@@ -209,7 +207,7 @@ filter {
}
```
-The extractor above generates a metrics named `log_count`, with tag key
`level` and value `1`, after this, you can
+The extractor above generates a metrics named `log_count`, with tag key
`level` and value `1`. After that, you can
configure MAL rules to calculate the log count grouping by logging level like
this:
```yaml
@@ -223,7 +221,7 @@ metrics:
```
-The other metrics generated is `http_response_time`, so that you can configure
MAL rules to generate more useful metrics
+The other metrics generated is `http_response_time`, so you can configure MAL
rules to generate more useful metrics
like percentiles.
```yaml
@@ -237,17 +235,17 @@ metrics:
### Sink
Sinks are the persistent layer of the LAL. By default, all the logs of each
filter are persisted into the storage.
-However, there are some mechanisms that allow you to selectively save some
logs, or even drop all the logs after you've
+However, some mechanisms allow you to selectively save some logs, or even drop
all the logs after you've
extracted useful information, such as metrics.
#### Sampler
-Sampler allows you to save the logs in a sampling manner. Currently, sampling
strategy `rateLimit` is supported, welcome
-to contribute more sampling strategies. If multiple samplers are specified,
the last one determines the final sampling
-result, see examples in [Enforcer](#enforcer).
+Sampler allows you to save the logs in a sampling manner. Currently, the
sampling strategy `rateLimit` is supported. We welcome
+contributions on more sampling strategies. If multiple samplers are specified,
the last one determines the final sampling
+result. See examples in [Enforcer](#enforcer).
-`rateLimit` samples `n` logs at most in 1 second. `rateLimit("SamplerID")`
requires an ID for the sampler, sampler
-declarations with the same ID share the same sampler instance, and thus share
the same `qps`, resetting logics.
+`rateLimit` samples `n` logs at a maximum rate of 1 second.
`rateLimit("SamplerID")` requires an ID for the sampler. Sampler
+declarations with the same ID share the same sampler instance, thus sharing
the same `qps` and resetting logic.
Examples:
@@ -273,8 +271,8 @@ filter {
#### Dropper
-Dropper is a special sink, meaning that all the logs are dropped without any
exception. This is useful when you want to
-drop debugging logs,
+Dropper is a special sink, meaning that all logs are dropped without any
exception. This is useful when you want to
+drop debugging logs.
```groovy
filter {
@@ -292,7 +290,7 @@ filter {
}
```
-or you have multiple filters, some of which are for extracting metrics, only
one of them needs to be persisted.
+Or if you have multiple filters, some of which are for extracting metrics,
only one of them has to be persisted.
```groovy
filter { // filter A: this is for persistence
@@ -319,9 +317,9 @@ filter { // filter B:
#### Enforcer
-Enforcer is another special sink that forcibly samples the log, a typical use
case of enforcer is when you have
-configured a sampler and want to save some logs forcibly, for example, to save
error logs even if the sampling mechanism
-is configured.
+Enforcer is another special sink that forcibly samples the log. A typical use
case of enforcer is when you have
+configured a sampler and want to save some logs forcibly, such as to save
error logs even if the sampling mechanism
+has been configured.
```groovy
filter {
