Skip to content
Permalink
Browse files
Merge branch 'trunk' into OAK-9740
  • Loading branch information
klcodanr committed May 24, 2022
2 parents 0457314 + c5eb75a commit bcf0492c2ba33e4526d097d46f3570dad7e885aa
Showing 46 changed files with 1,356 additions and 277 deletions.
@@ -71,6 +71,7 @@
org.apache.jackrabbit.oak.plugins.observation.filter,
org.apache.jackrabbit.oak.plugins.tree.factories,
org.apache.jackrabbit.oak.plugins.version,
org.apache.jackrabbit.oak.plugins.metric.util
</Export-Package>
<Jaas-ModuleClass>
org.apache.jackrabbit.oak.spi.security.authentication.GuestLoginModule,
@@ -0,0 +1,67 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.jackrabbit.oak.plugins.metric.util;

import org.apache.jackrabbit.oak.stats.CounterStats;
import org.apache.jackrabbit.oak.stats.HistogramStats;
import org.apache.jackrabbit.oak.stats.MeterStats;
import org.apache.jackrabbit.oak.stats.StatisticsProvider;
import org.apache.jackrabbit.oak.stats.StatsOptions;
import org.apache.jackrabbit.oak.stats.TimerStats;
import org.jetbrains.annotations.NotNull;

import java.util.Map;
import java.util.function.BiFunction;

/**
* Util class to generate a name for Stats implementations that can be used for creating labels in prometheus.
* Usage - StatsProviderUtil(<StatisticsProvider Object>).getHistoStats().apply(metricName, labels)
* where metricName is a String to denote the metric name and labels is map of label values.
* Resultant metric will be created with a name as follows -
* metricName;labelName1=labelValue1;labelName2=labelValue2
* This can then be translated by a consuming alerting system like prometheus into metric name and labels separately.
*/
public class StatsProviderUtil {

private final StatisticsProvider statisticsProvider;
private final BiFunction<String, Map<String, String>, String> METRIC = (name, labels) -> labels.entrySet().stream().reduce(name,
(n, e) -> n + ";" + e.getKey() + "=" + e.getValue(),
(n1, n2) -> n1 + n2);

public StatsProviderUtil(@NotNull StatisticsProvider statisticsProvider) {
this.statisticsProvider = statisticsProvider;
}

public BiFunction<String, Map<String, String>, HistogramStats> getHistoStats() {
return (name, labels) -> statisticsProvider.getHistogram(METRIC.apply(name, labels), StatsOptions.METRICS_ONLY);
}

public BiFunction<String, Map<String, String>, CounterStats> getCounterStats() {
return (name, labels) -> statisticsProvider.getCounterStats(METRIC.apply(name, labels), StatsOptions.METRICS_ONLY);
}

public BiFunction<String, Map<String, String>, TimerStats> getTimerStats() {
return (name, labels) -> statisticsProvider.getTimer(METRIC.apply(name, labels), StatsOptions.METRICS_ONLY);
}

public BiFunction<String, Map<String, String>, MeterStats> getMeterStats() {
return (name, labels) -> statisticsProvider.getMeter(METRIC.apply(name, labels), StatsOptions.METRICS_ONLY);
}

}
@@ -0,0 +1,24 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

/**
* Oak plugins metric util. This package contains StatsProvideUtil.
*/
@Version("0.0.1")
package org.apache.jackrabbit.oak.plugins.metric.util;

import org.osgi.annotation.versioning.Version;
@@ -23,6 +23,7 @@
import static org.apache.jackrabbit.JcrConstants.NT_BASE;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Set;
import java.util.concurrent.TimeUnit;
@@ -36,6 +37,7 @@
import org.apache.jackrabbit.oak.commons.PathUtils;
import org.apache.jackrabbit.oak.core.ImmutableRoot;
import org.apache.jackrabbit.oak.plugins.memory.PropertyBuilder;
import org.apache.jackrabbit.oak.plugins.metric.util.StatsProviderUtil;
import org.apache.jackrabbit.oak.plugins.tree.TreeUtil;
import org.apache.jackrabbit.oak.query.ExecutionContext;
import org.apache.jackrabbit.oak.query.QueryEngineSettings;
@@ -392,8 +394,10 @@ private void measure(long timeNanos) {
TimerStats t = timerDuration;
if (t == null) {
// reuse the timer (in the normal case)
t = timerDuration = query.getSettings().getStatisticsProvider().
getTimer("QUERY_DURATION_" + planIndexName, StatsOptions.METRICS_ONLY);
// QUERY_DURATION;index=<planIndexName> will be translated as metric name = QUERY_DURATION
// and index=<planIndexName> as a label by a downstream consumer like prometheus.
StatsProviderUtil statsProviderUtil = new StatsProviderUtil(query.getSettings().getStatisticsProvider());
t = timerDuration = statsProviderUtil.getTimerStats().apply("QUERY_DURATION", Collections.singletonMap("index", planIndexName));
}
t.update(timeNanos, TimeUnit.NANOSECONDS);
}
@@ -14,8 +14,14 @@
See the License for the specific language governing permissions and
limitations under the License.
-->

Best Practices when Using Jackrabbit Oak
--------------------------------------------------------------------------------

## Session refresh behavior
<!-- MACRO{toc} -->

## Session Management
### Session refresh behavior

Oak is based on the MVCC model where each session starts with a snapshot
view of the repository. Concurrent changes from other sessions *are not
@@ -51,6 +57,7 @@ In this case the stack trace of the other session involved will also be
logged. For efficiency reasons the stack trace will not be logged if
`DEBUG` level is not enabled.

## Content Modelling
### Large number of direct child node

Oak scales to large number of direct child nodes of a node as long as those
@@ -88,13 +95,7 @@ If the file has no need to be referenceable it is recommended to use the
node type `oak:Resource` instead and add the mixin type `mix:referenceble`
only upon demand (see [OAK-4567](https://issues.apache.org/jira/browse/OAK-4567))

### Don't use Thread.interrupt()

`Thread.interrupt()` can severely impact or even stop the repository. The reason for
this is that Oak internally uses various classes from the `nio` package that implement
`InterruptibleChannel`, which are [asynchronously closed](http://docs.oracle.com/javase/7/docs/api/java/nio/channels/InterruptibleChannel.html)
when receiving an `InterruptedException` while blocked on IO. See [OAK-2609](https://issues.apache.org/jira/browse/OAK-2609).

## Hierarchy Operations
### Tree traversal

As explained in [Understanding the node state model](https://jackrabbit.apache.org/oak/docs/architecture/nodestate.html), Oak stores content in a tree hierarchy.
@@ -115,4 +116,14 @@ d = c.getNode("d"); // preferred way to fetch the ch
// get the parent node
c = session.getNode("/a/b/c");
c = d.getParent(); // preferred way to fetch the parent node
```
```
## Security
- [Best Practices for Authorization](https://jackrabbit.apache.org/oak/docs/security/authorization/bestpractices.html)

## Misc
### Don't use Thread.interrupt()

`Thread.interrupt()` can severely impact or even stop the repository. The reason for
this is that Oak internally uses various classes from the `nio` package that implement
`InterruptibleChannel`, which are [asynchronously closed](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/channels/InterruptibleChannel.html)
when receiving an `InterruptedException` while blocked on IO. See [OAK-2609](https://issues.apache.org/jira/browse/OAK-2609).
@@ -40,7 +40,7 @@ however there are differences:
* `functionName` is ignored.
* `name` is ignored.
* `indexPath` is ignored.
* `analyzers` is ignored.
* `analyzers` is ignored, except for `indexOriginalTerm`.
* For property definitions, `sync` and `unique` are ignored.
* The behavior for `dynamicBoost` is slightly different:
For Lucene indexes, boosting is done in indexing, while for Elastic it is done at query time.
@@ -32,13 +32,13 @@ We currently support the following maintenance branches:

* [Oak 1.22](https://github.com/apache/jackrabbit-oak/tree/1.22/) ([download](https://jackrabbit.apache.org/jcr/downloads.html#oak1.22)) - from Java 8 up to Java 13
* [Oak 1.8](https://github.com/apache/jackrabbit-oak/tree/1.8/) ([download](https://jackrabbit.apache.org/jcr/downloads.html#oak1.8)) - from Java 8 up to Java 13
* [Oak 1.6](https://github.com/apache/jackrabbit-oak/tree/1.6/) ([download](https://jackrabbit.apache.org/jcr/downloads.html#oak1.6)) - recommended version for Java 7 (Java 8 and later since 1.6.21) - "end of life" planned for Spring 2022

End of life
-----------
The following branches have reached "end of life":

* [Oak 1.10](https://github.com/apache/jackrabbit-oak/tree/1.10/)
* [Oak 1.6](https://github.com/apache/jackrabbit-oak/tree/1.6/)
* [Oak 1.4](https://github.com/apache/jackrabbit-oak/tree/1.4/)
* [Oak 1.2](https://github.com/apache/jackrabbit-oak/tree/1.2/)
* [Oak 1.0](https://github.com/apache/jackrabbit-oak/tree/1.0/)
@@ -99,6 +99,10 @@ restriction management that allows to narrow the effect of permissions to
items matching a given, defined behavior. Details can be found in section
[RestrictionManagement](authorization/restriction.html#pluggability).

<a name="best_practices"></a>
### Best Proctices
See section [Best Practices for authorization](authorization/bestpractices.html).

<a name="further_reading"></a>
### Further Reading

0 comments on commit bcf0492

Please sign in to comment.