Skip to content

Commit fc8f117

Browse files
bhufmannbhufmann
committed
doc: Add a developer guide tailored for trace-server development
- Add developer guide in markdown in doc/trace-server folder - Update and create example classes in the o.e.tc.example.core plug-in Signed-off-by: Bernd Hufmann <[email protected]>
1 parent 9e6e44f commit fc8f117

16 files changed

+4394
-7
lines changed

‎doc/org.eclipse.tracecompass.examples.core/META-INF/MANIFEST.MF‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,12 @@ Bundle-ActivationPolicy: lazy
1414
Bundle-RequiredExecutionEnvironment: JavaSE-17
1515
Export-Package: org.eclipse.tracecompass.examples.core,
1616
org.eclipse.tracecompass.examples.core.analysis,
17-
org.eclipse.tracecompass.examples.core.data.provider
17+
org.eclipse.tracecompass.examples.core.analysis.config,
18+
org.eclipse.tracecompass.examples.core.data.provider,
19+
org.eclipse.tracecompass.examples.core.data.provider.config
1820
Bundle-Vendor: %Bundle-Vendor
19-
Import-Package: com.google.common.collect
21+
Import-Package: com.google.common.collect,
22+
com.google.gson;version="2.8.2",
23+
com.google.gson.annotations;version="2.8.2",
24+
com.google.gson.reflect;version="2.8.2"
2025
Automatic-Module-Name: org.eclipse.tracecompass.examples.core

‎doc/org.eclipse.tracecompass.examples.core/plugin.xml‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,15 @@
1212
class="org.eclipse.tracecompass.tmf.core.trace.TmfTrace">
1313
</tracetype>
1414
</module>
15+
<module
16+
id="org.eclipse.tracecompass.examples.state.system.module.config"
17+
name="Example State System Module"
18+
analysis_module="org.eclipse.tracecompass.examples.core.analysis.config.ExampleConfigurableStateSystemAnalysisModule"
19+
automatic="false">
20+
<tracetype
21+
class="org.eclipse.tracecompass.tmf.core.trace.TmfTrace">
22+
</tracetype>
23+
</module>
1524
</extension>
1625
<extension point="org.eclipse.tracecompass.tmf.core.dataprovider">
1726
<dataProviderFactory
@@ -23,8 +32,16 @@
2332
id="org.eclipse.tracecompass.examples.xy.dataprovider">
2433
</dataProviderFactory>
2534
<dataProviderFactory
26-
class="org.eclipse.tracecompass.examples.core.data.provider.ExampleEventsStatisticsDataProviderFactory"
35+
class="org.eclipse.tracecompass.examples.core.data.provider.ExampleDataTreeDataProviderFactory"
2736
id="org.eclipse.tracecompass.examples.nomodulestats">
2837
</dataProviderFactory>
38+
<dataProviderFactory
39+
class="org.eclipse.tracecompass.examples.core.data.provider.config.ExampleConfigurableDataTreeDataProviderFactory"
40+
id="org.eclipse.tracecompass.examples.nomodulestats.config">
41+
</dataProviderFactory>
42+
<dataProviderFactory
43+
class="org.eclipse.tracecompass.examples.core.data.provider.config.ExampleConfigurableTimeGraphProviderFactory"
44+
id="org.eclipse.tracecompass.examples.timegraph.dataprovider.config">
45+
</dataProviderFactory>
2946
</extension>
3047
</plugin>

‎doc/org.eclipse.tracecompass.examples.core/schema/example-schema-cpu.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://org.eclipse.tracecompass/example-schema.json",
4+
"title": "Example Schema",
5+
"description": "Example Schema for event statistics",
6+
"type": "object",
7+
"properties": {
8+
"filter": {
9+
"description": "filter regular expressions",
10+
"type": "string"
11+
}
12+
},
13+
"required": ["filter"]
14+
}

‎doc/org.eclipse.tracecompass.examples.core/schema/example-schema.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://org.eclipse.tracecompass/example-schema.json",
4+
"title": "Example Schema for cpu",
5+
"description": "Example Schema for cpu",
6+
"type": "object",
7+
"properties": {
8+
"filter": {
9+
"description": "cpu number",
10+
"type": "number"
11+
}
12+
},
13+
"required": ["filter"]
14+
}

‎doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/Activator.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@
1919
*/
2020
public class Activator extends Plugin {
2121

22+
/** The plug-in ID */
23+
public static String PLUGIN_ID = "org.eclipse.tracecompass.examples.core"; //$NON-NLS-1$
24+
2225
// ------------------------------------------------------------------------
2326
// Attributes
2427
// ------------------------------------------------------------------------

‎doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/analysis/config/ExampleConfigurableStateProvider.java‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
/*******************************************************************************
2+
* Copyright (c) 2025 École Polytechnique de Montréal and others
3+
*
4+
* All rights reserved. This program and the accompanying materials are
5+
* made available under the terms of the Eclipse Public License 2.0 which
6+
* accompanies this distribution, and is available at
7+
* https://www.eclipse.org/legal/epl-2.0/
8+
*
9+
* SPDX-License-Identifier: EPL-2.0
10+
*******************************************************************************/
11+
12+
package org.eclipse.tracecompass.examples.core.analysis.config;
13+
14+
import java.util.Map;
15+
import java.util.Objects;
16+
17+
import org.eclipse.jdt.annotation.NonNull;
18+
import org.eclipse.jdt.annotation.Nullable;
19+
import org.eclipse.tracecompass.statesystem.core.ITmfStateSystemBuilder;
20+
import org.eclipse.tracecompass.tmf.core.config.ITmfConfiguration;
21+
import org.eclipse.tracecompass.tmf.core.event.ITmfEvent;
22+
import org.eclipse.tracecompass.tmf.core.event.aspect.TmfCpuAspect;
23+
import org.eclipse.tracecompass.tmf.core.statesystem.AbstractTmfStateProvider;
24+
import org.eclipse.tracecompass.tmf.core.statesystem.ITmfStateProvider;
25+
import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
26+
import org.eclipse.tracecompass.tmf.core.trace.TmfTraceUtils;
27+
28+
import com.google.gson.Gson;
29+
import com.google.gson.JsonSyntaxException;
30+
import com.google.gson.annotations.Expose;
31+
import com.google.gson.annotations.SerializedName;
32+
33+
/**
34+
* An example of a simple state provider for a simple state system analysis
35+
*
36+
* This module is also in the developer documentation of Trace Compass. If it is
37+
* modified here, the doc should also be updated.
38+
*
39+
* @author Alexandre Montplaisir
40+
* @author Geneviève Bastien
41+
* @author Bernd Hufmann
42+
*/
43+
public class ExampleConfigurableStateProvider extends AbstractTmfStateProvider {
44+
45+
private static final @NonNull String PROVIDER_ID = "org.eclipse.tracecompass.examples.state.system.module.config"; //$NON-NLS-1$
46+
private static final int VERSION = 0;
47+
private int fCpu = -1;
48+
49+
/**
50+
* Constructor
51+
*
52+
* @param trace
53+
* the trace
54+
* @param configuration
55+
* the configuration
56+
*/
57+
public ExampleConfigurableStateProvider(@NonNull ITmfTrace trace, @Nullable ITmfConfiguration configuration) {
58+
super(trace, PROVIDER_ID + (configuration == null ? "" : ":" + configuration.getId())); //$NON-NLS-1$ //$NON-NLS-2$
59+
if (configuration != null) {
60+
try {
61+
String jsonParameters = new Gson().toJson(configuration.getParameters(), Map.class);
62+
@SuppressWarnings("null")
63+
Integer cpu = new Gson().fromJson(jsonParameters, InternalConfiguration.class).getCpu();
64+
if (cpu != null) {
65+
fCpu = cpu.intValue();
66+
}
67+
} catch (JsonSyntaxException e) {
68+
fCpu = -1;
69+
}
70+
}
71+
}
72+
73+
/**
74+
* Constructor
75+
*
76+
* @param trace
77+
* The trace for this state provider
78+
*/
79+
public ExampleConfigurableStateProvider(@NonNull ITmfTrace trace) {
80+
super(trace, PROVIDER_ID);
81+
}
82+
83+
@Override
84+
public int getVersion() {
85+
return VERSION;
86+
}
87+
88+
@Override
89+
public @NonNull ITmfStateProvider getNewInstance() {
90+
return new ExampleConfigurableStateProvider(getTrace());
91+
}
92+
93+
@Override
94+
protected void eventHandle(ITmfEvent event) {
95+
96+
/**
97+
* Do what needs to be done with this event, here is an example that
98+
* updates the CPU state and TID after a sched_switch
99+
*/
100+
if (event.getName().equals("sched_switch")) { //$NON-NLS-1$
101+
102+
final long ts = event.getTimestamp().getValue();
103+
Long nextTid = event.getContent().getFieldValue(Long.class, "next_tid"); //$NON-NLS-1$
104+
Integer cpu = TmfTraceUtils.resolveIntEventAspectOfClassForEvent(event.getTrace(), TmfCpuAspect.class, event);
105+
if (cpu == null || nextTid == null || (fCpu >= 0 && cpu != fCpu)) {
106+
return;
107+
}
108+
109+
ITmfStateSystemBuilder ss = Objects.requireNonNull(getStateSystemBuilder());
110+
int quark = ss.getQuarkAbsoluteAndAdd("CPUs", String.valueOf(cpu)); //$NON-NLS-1$
111+
// The main quark contains the tid of the running thread
112+
ss.modifyAttribute(ts, nextTid, quark);
113+
114+
// The status attribute has an integer value
115+
int statusQuark = ss.getQuarkRelativeAndAdd(quark, "Status"); //$NON-NLS-1$
116+
Integer value = (nextTid > 0 ? 1 : 0);
117+
ss.modifyAttribute(ts, value, statusQuark);
118+
}
119+
}
120+
121+
122+
private static class InternalConfiguration {
123+
@Expose
124+
@SerializedName(value = "cpu")
125+
private @Nullable Integer fCpuValue = null;
126+
127+
public @Nullable Integer getCpu() {
128+
return fCpuValue;
129+
}
130+
}
131+
}

‎doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/analysis/config/ExampleConfigurableStateSystemAnalysisModule.java‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
/*******************************************************************************
2+
* Copyright (c) 2020 École Polytechnique de Montréal and others
3+
*
4+
* All rights reserved. This program and the accompanying materials are
5+
* made available under the terms of the Eclipse Public License 2.0 which
6+
* accompanies this distribution, and is available at
7+
* https://www.eclipse.org/legal/epl-2.0/
8+
*
9+
* SPDX-License-Identifier: EPL-2.0
10+
*******************************************************************************/
11+
12+
package org.eclipse.tracecompass.examples.core.analysis.config;
13+
14+
import java.util.Objects;
15+
16+
import org.eclipse.jdt.annotation.NonNull;
17+
import org.eclipse.jdt.annotation.Nullable;
18+
import org.eclipse.tracecompass.tmf.core.config.ITmfConfiguration;
19+
import org.eclipse.tracecompass.tmf.core.statesystem.ITmfStateProvider;
20+
import org.eclipse.tracecompass.tmf.core.statesystem.TmfStateSystemAnalysisModule;
21+
22+
/**
23+
* An example of a simple state system analysis module.
24+
*
25+
* This module is also in the developer documentation of Trace Compass. If it is
26+
* modified here, the doc should also be updated.
27+
*
28+
* @author Geneviève Bastien
29+
* @author Bernd Hufmann
30+
*/
31+
public class ExampleConfigurableStateSystemAnalysisModule extends TmfStateSystemAnalysisModule {
32+
33+
/**
34+
* Module ID
35+
*/
36+
public static final String ID = "org.eclipse.tracecompass.examples.state.system.module.config"; //$NON-NLS-1$
37+
38+
/**
39+
* The configuration to apply.
40+
*/
41+
private ITmfConfiguration fConfiguration = null;
42+
43+
/**
44+
* Default constructor
45+
*/
46+
public ExampleConfigurableStateSystemAnalysisModule() {
47+
super();
48+
}
49+
50+
/**
51+
* Constructor
52+
*
53+
* @param configuration
54+
* the configuration
55+
*/
56+
public ExampleConfigurableStateSystemAnalysisModule(ITmfConfiguration configuration) {
57+
fConfiguration = configuration;
58+
if (configuration != null) {
59+
setId(ID + ":" + fConfiguration.getId()); //$NON-NLS-1$
60+
}
61+
}
62+
63+
@Override
64+
protected @NonNull ITmfStateProvider createStateProvider() {
65+
return new ExampleConfigurableStateProvider(Objects.requireNonNull(getTrace()), fConfiguration);
66+
}
67+
68+
@Override
69+
public @Nullable ITmfConfiguration getConfiguration() {
70+
return fConfiguration;
71+
}
72+
}

doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/data/provider/ExampleEventsStatisticsDataProvider.java renamed to doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/data/provider/ExampleDataTreeDataProvider.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242
*/
4343
@SuppressWarnings("null")
4444
@NonNullByDefault
45-
public class ExampleEventsStatisticsDataProvider implements ITmfTreeDataProvider<TmfTreeDataModel> {
45+
public class ExampleDataTreeDataProvider implements ITmfTreeDataProvider<TmfTreeDataModel> {
4646
private static long fCount = 0;
4747

4848
private @Nullable ITmfTrace fTrace;
@@ -54,7 +54,7 @@ public class ExampleEventsStatisticsDataProvider implements ITmfTreeDataProvider
5454
* @param trace
5555
* the trace (not experiment)
5656
*/
57-
public ExampleEventsStatisticsDataProvider(ITmfTrace trace) {
57+
public ExampleDataTreeDataProvider(ITmfTrace trace) {
5858
fTrace = trace;
5959
}
6060

doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/data/provider/ExampleEventsStatisticsDataProviderFactory.java renamed to doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/data/provider/ExampleDataTreeDataProviderFactory.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
/**
3030
* Example data provider factory
3131
*/
32-
public class ExampleEventsStatisticsDataProviderFactory implements IDataProviderFactory {
32+
public class ExampleDataTreeDataProviderFactory implements IDataProviderFactory {
3333
private static final String ID = "org.eclipse.tracecompass.examples.nomodulestats"; //$NON-NLS-1$
3434

3535
private static final IDataProviderDescriptor DESCRIPTOR = new DataProviderDescriptor.Builder()
@@ -44,7 +44,7 @@ public class ExampleEventsStatisticsDataProviderFactory implements IDataProvider
4444
if (trace instanceof TmfExperiment) {
4545
return TmfTreeCompositeDataProvider.create(TmfTraceManager.getTraceSet(trace), ID);
4646
}
47-
return new ExampleEventsStatisticsDataProvider(trace);
47+
return new ExampleDataTreeDataProvider(trace);
4848
}
4949

5050
@SuppressWarnings("null")

0 commit comments

Comments
 (0)