1 /*
2 * Copyright (C) 2018, David Pursehouse <david.pursehouse@gmail.com>
3 * and other copyright owners as documented in the project's IP log.
4 *
5 * This program and the accompanying materials are made available
6 * under the terms of the Eclipse Distribution License v1.0 which
7 * accompanies this distribution, is reproduced below, and is
8 * available at http://www.eclipse.org/org/documents/edl-v10.php
9 *
10 * All rights reserved.
11 *
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
14 * conditions are met:
15 *
16 * - Redistributions of source code must retain the above copyright
17 * notice, this list of conditions and the following disclaimer.
18 *
19 * - Redistributions in binary form must reproduce the above
20 * copyright notice, this list of conditions and the following
21 * disclaimer in the documentation and/or other materials provided
22 * with the distribution.
23 *
24 * - Neither the name of the Eclipse Foundation, Inc. nor the
25 * names of its contributors may be used to endorse or promote
26 * products derived from this software without specific prior
27 * written permission.
28 *
29 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
30 * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
31 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
32 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
33 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
34 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
35 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
36 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
37 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
38 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
39 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
40 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
41 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
42 */
43 package org.eclipse.jgit.storage.file;
44
45 import java.util.Map;
46
47 import javax.management.MXBean;
48
49 import org.eclipse.jgit.internal.storage.file.WindowCache;
50
51 /**
52 * Cache statistics for {@link WindowCache}.
53 *
54 * @since 4.11
55 */
56 @MXBean
57 public interface WindowCacheStats {
58 /**
59 * @return the number of open files.
60 * @deprecated use {@link #getOpenFileCount()} instead
61 */
62 @Deprecated
63 public static int getOpenFiles() {
64 return (int) WindowCache.getInstance().getStats().getOpenFileCount();
65 }
66
67 /**
68 * @return the number of open bytes.
69 * @deprecated use {@link #getOpenByteCount()} instead
70 */
71 @Deprecated
72 public static long getOpenBytes() {
73 return WindowCache.getInstance().getStats().getOpenByteCount();
74 }
75
76 /**
77 * @return cache statistics for the WindowCache
78 * @since 5.1.13
79 */
80 public static WindowCacheStats getStats() {
81 return WindowCache.getInstance().getStats();
82 }
83
84 /**
85 * Number of cache hits
86 *
87 * @return number of cache hits
88 */
89 long getHitCount();
90
91 /**
92 * Ratio of cache requests which were hits defined as
93 * {@code hitCount / requestCount}, or {@code 1.0} when
94 * {@code requestCount == 0}. Note that {@code hitRate + missRate =~ 1.0}.
95 *
96 * @return the ratio of cache requests which were hits
97 */
98 default double getHitRatio() {
99 long requestCount = getRequestCount();
100 return (requestCount == 0) ? 1.0
101 : (double) getHitCount() / requestCount;
102 }
103
104 /**
105 * Number of cache misses.
106 *
107 * @return number of cash misses
108 */
109 long getMissCount();
110
111 /**
112 * Ratio of cache requests which were misses defined as
113 * {@code missCount / requestCount}, or {@code 0.0} when
114 * {@code requestCount == 0}. Note that {@code hitRate + missRate =~ 1.0}.
115 * Cache misses include all requests which weren't cache hits, including
116 * requests which resulted in either successful or failed loading attempts.
117 *
118 * @return the ratio of cache requests which were misses
119 */
120 default double getMissRatio() {
121 long requestCount = getRequestCount();
122 return (requestCount == 0) ? 0.0
123 : (double) getMissCount() / requestCount;
124 }
125
126 /**
127 * Number of successful loads
128 *
129 * @return number of successful loads
130 */
131 long getLoadSuccessCount();
132
133 /**
134 * Number of failed loads
135 *
136 * @return number of failed loads
137 */
138 long getLoadFailureCount();
139
140 /**
141 * Ratio of cache load attempts which threw exceptions. This is defined as
142 * {@code loadFailureCount / (loadSuccessCount + loadFailureCount)}, or
143 * {@code 0.0} when {@code loadSuccessCount + loadFailureCount == 0}.
144 *
145 * @return the ratio of cache loading attempts which threw exceptions
146 */
147 default double getLoadFailureRatio() {
148 long loadFailureCount = getLoadFailureCount();
149 long totalLoadCount = getLoadSuccessCount() + loadFailureCount;
150 return (totalLoadCount == 0) ? 0.0
151 : (double) loadFailureCount / totalLoadCount;
152 }
153
154 /**
155 * Total number of times that the cache attempted to load new values. This
156 * includes both successful load operations, as well as failed loads. This
157 * is defined as {@code loadSuccessCount + loadFailureCount}.
158 *
159 * @return the {@code loadSuccessCount + loadFailureCount}
160 */
161 default long getLoadCount() {
162 return getLoadSuccessCount() + getLoadFailureCount();
163 }
164
165 /**
166 * Number of cache evictions
167 *
168 * @return number of evictions
169 */
170 long getEvictionCount();
171
172 /**
173 * Ratio of cache evictions. This is defined as
174 * {@code evictionCount / requestCount}, or {@code 0.0} when
175 * {@code requestCount == 0}.
176 *
177 * @return the ratio of cache loading attempts which threw exceptions
178 */
179 default double getEvictionRatio() {
180 long evictionCount = getEvictionCount();
181 long requestCount = getRequestCount();
182 return (requestCount == 0) ? 0.0
183 : (double) evictionCount / requestCount;
184 }
185
186 /**
187 * Number of times the cache returned either a cached or uncached value.
188 * This is defined as {@code hitCount + missCount}.
189 *
190 * @return the {@code hitCount + missCount}
191 */
192 default long getRequestCount() {
193 return getHitCount() + getMissCount();
194 }
195
196 /**
197 * Average time in nanoseconds for loading new values. This is
198 * {@code totalLoadTime / (loadSuccessCount + loadFailureCount)}.
199 *
200 * @return the average time spent loading new values
201 */
202 default double getAverageLoadTime() {
203 long totalLoadCount = getLoadSuccessCount() + getLoadFailureCount();
204 return (totalLoadCount == 0) ? 0.0
205 : (double) getTotalLoadTime() / totalLoadCount;
206 }
207
208 /**
209 * Total time in nanoseconds the cache spent loading new values.
210 *
211 * @return the total number of nanoseconds the cache has spent loading new
212 * values
213 */
214 long getTotalLoadTime();
215
216 /**
217 * Number of pack files kept open by the cache
218 *
219 * @return number of files kept open by cache
220 */
221 long getOpenFileCount();
222
223 /**
224 * Number of bytes cached
225 *
226 * @return number of bytes cached
227 */
228 long getOpenByteCount();
229
230 /**
231 * Number of bytes cached per repository
232 *
233 * @return number of bytes cached per repository
234 */
235 Map<String, Long> getOpenByteCountPerRepository();
236
237 /**
238 * Reset counters. Does not reset open bytes and open files counters.
239 */
240 void resetCounters();
241 }